(19) 



Eur paisch $ Pat ntamt 
Eur pean Patent Offl e 
Offi europeen d s brev ts 



(12) 



(id EP 0 770 958 A1 

EUROPEAN PATENT APPLICATION 



(43) Date of publication: 

02.05.1997 Bulletin 1997/18 



(51) mtci 6; G06F 9/455, G06F 13/10 



(21) Application number: 96307735.9 

(22) Date of filing: 25.10.1996 



(84) 


Designated Contracting States: 


• Karr, Ronald J. 


DE FR GB IT SE 


North Chelmsford, Massachusetts 01863 (US) 


(30) 


Priority: 27.10.1995 US 549372 


(74) Representative: W.P. Thompson & Co. 


Coopers Building, 


(71) 


Applicant SUN MICROSYSTEMS, INC. 


Church Street 


Mountain View, CA 94043 (US) 


Liverpool L1 3AB (GB) 


(72) 


Inventors: 




• 


Horan, Jeffrey A. 






Hopkinton, Massachusetts 01748 (US) 





(54) WinSock network socket driver subsystem and method for windows emulator running under 
unix operating system 



00 

m 

O) 

o 
o 

Q. 

UJ 



(57) A computer system comprising at least one ap- 
plications program, a Unix operating system API, and a 
WinSock socket driver. The applications program per- 
forms predetermined processing operations, and issues 
Windows operating system calls, including WinSock 
socket calls. The Unix operating system API provides, 
in response to Unix socket calls, Unix socket services 
in connection with at least one socket connection to an- 
other computer system over a network. The WinSock 
socket driver receives WinSock socket calls from said 
applications program and emulates the WinSock socket 
calls in connection with Unix socket calls to said Unix 
operating system API. In emulating at least some of the 
WinSock socket calls, the WinSock socket driver makes 
use of Unix socket calls at least some of which block, 
but effectively controls the computer system to execute 
such calls in a non-blocking manner. 
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D script ion 

The present invention relates generally to the field of digital computer systems and more specifically to arrange- 
ments for controlling communications among digital computer systems which may communicate over, for example, a 
5 network. 

In particular, the present invention provides a WinSock network socket driver system and method for use in con- 
nection with a Windows emulator running under the Unix operating system program, to provide WinSock socket services 
to Windows applications programs. 

The following references are incorporated herein by reference:- 

10 

a) "Windows Sockets: An Open Interface For Network Programming Under Microsoft® Windows™" Version 1.1, 
20 January 1993, (hereinafter referred to as "the WinSock specification") attached hereto as a Appendix A; and 

b) "The X Toolkit Intrinsics Reference Manual" (O'Reilly & Associates: 1990), copyright page and pages 86-83, 
301 and 304 attached hereto as Appendix B. 

15 

In modern "enterprise" computing, personal computers and workstations distributed among workers in the enter- 
prise are replacing the previously-used large and expensive, centrally-located and maintained mainframe computer 
systems. One advantage that mainframe systems have over more modern distributed arrangements, however, is that, 
since they are centrally-located, they more easily provide for sharing of data and programs, which can be important in 
20 an enterprise environment. To facilitate program and data sharing among personal computers and workstations, net- 
works have been developed over which one personal computer or workstation can make use of data and programs 
on another "remote" device, in general by causing the data and programs to be "downloaded," that is, transferred to 
it for processing. 

A number of network communication paradigms have been developed to help facilitate communications over a 

2S network, including, for example, virtual circuits, "sockets" or the like. Using such paradigms, an applications program 
executing on one computer system may transmit data to, or receive data from, another computer system over th 
network merely by referencing an underlying virtual circuit or socket. The network operating system will receive the 
data and perform the actual transfer. Indeed, the applications program may not even need to be aware that the data 
is being transferred to, or received from, another computer system . 

30 A number of operating system programs may be used in the various computer systems connected to a network, 

including the well-known Unix operating system program and the Microsoft Windows operating system program. The 
socket network transfer paradigm was developed by the University of California at Berkeley, and have been popularized 
in its Berkeley Software Distribution ("BSD"). The BSD Unix Sockets paradigm defines a number of function calls which 
allow an applications program to control and access a number of network events. A similar socket paradigm has been 

3S developed for Windows, identified as "WinSock", which includes the Unix socket calls and a number of additional calls 
(Windows "extensions") provided to allow applications programs to have message-based, asynchronous access to a 
variety of network events. A number of the BSD Unix socket calls are "blocking," that is, when an applications program 
issues a socket call, the applications program does not receive the results until the operation requested in the call has 
been completed. A number of the socket calls may take an arbitrary period of time to complete. In connection with 

40 Windows, however, it is preferable that the WinSock calls be performed in a non-blocking manner. 

SUMMARY OF THE INVENTION 

The invention provides a new and improved WinSock network socket driver system and method for use in con- 
45 nection with a Windows emulator operating under the Unix operating system program, to provide WinSock socket 
services for Windows applications programs operating under the Windows emulator. 

In brief summary, in one aspect the invention provides a computer system comprising at least one applications 
program, a Unix operating system API , and a WinSock socket driver The applications program performs predetermined 
processing operations, and issues Windows operating system calls, including WinSock socket calls. The Unix operating 
so system API providing, in response to Unix socket calls, Unix socket services in connection with at least one socket 
connection to another computer system over a network. The WinSock socket driver receives WinSock socket calls 
from said applications program and emulates the WinSock socket calls in connection with Unix socket calls to said 
Unix operating system API. 

In another aspect, the invention provides a non-pre-emptive multi-tasking emulator, for use in connection with a 
ss computer, for emulating a blockable call issued by an applications program. Th blockabl call has a duration parameter . 
which specifies a duration over which a specified operation to be performed. The blockable call blocks other operations 
for th duration while the blockable call is being executed. The emulator emulates the blockable call in a non-blocking 
mann r. The emulator comprises a timer, a blockable call issuer and a non-blockable iteration control element. The 
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timer enabl s generation ofa timing indication at the end of a timing interval corresponding to the duration specified 
by the duration parameter. Th blockable call issuer issues the blockable call with a duration parameter specifying an 
instantaneous duration thereby enabling the specified operation to be performed instantaneously. Finally, the non- 
blockable iteration control element, in a series of iterations, enables the blockabl call issuer to issue the blockable 
5 call until the timer generates th timing indication. The non-blockable control element is non-pre-emptiv ly interruptible 
during each iteration, at least while the blockable call is not being executed, thereby to provide for the non-blocking 
emulation of the otherwise blockable call. 

The present invention will now be further described, by way of example, with reference to the accompanying 
drawings, in which: - 

w 

FIG. 1 depicts an illustrative computer system incorporating a network socket driver arrangement in accordance 
with the invention; 

FIG. 2 schematically represents a functional block diagram of the network socket driver in relation to other functional 
is elements of the computer system depicted in FIG. 1 ; and 

FIGs. 3 and 4 depict flow diagrams illustrating operations performed by the network socket driver, which are useful 
in understanding the invention. 

20 DETAILED DESCRIPTION OF AN ILLUSTRATIVE EMBODIMENT 

FIG. 1 depicts an illustrative computer system 10 constructed in accordance with the invention. With reference to 
FIG. 1 , the computer system 10 in one embodiment includes a processor module 11 and operator interface elements 
comprising operator input components such as a keyboard 1 2A and/or a mouse 12B (generally identified as operator 

2$ input element(s) 12) and an operator output element such as a video display device 13. The illustrative computer 
system 10 is of the conventional stored-program computer architecture. The processor module 11 includes, for exam- 
ple, processor, memory and mass storage devices such as disk and/or tape storage elements (not separately shown) 
which perform processing and storage operations in connection with digital data provided thereto. The operator input 
element(s) 12 are provided to permit an operator to input information for processing. The video display device 13 is 

30 provided to display output information generated by the processor module 11 on a screen 14 to the operator, including 
data that the operator may input for processing, information that the operator may input to control processing, as well 
as information generated during processing. The processor module 11 generates information for display by the video 
display device 13 using a so-called "graphical user interface" ("GUI"), in which information for various applications 
programs is displayed using various "windows." Although the computer system 10 is shown as comprising particular 

35 components, such as the keyboard 12A and mouse 12B for receiving input information from an operator, and a video 
display device 1 3 for displaying output information to the operator, it will be appreciated that the computer system JO 
may include a variety of components in addition to or instead of those depicted in FIG. 1 

In addition, the processor module 11 includes one or more network ports, generally identified by reference numeral 
14, which are connected to communication links which connect the computer system 10 in a computer network. The 

40 network ports enable the computer system 10 to transmit information to, and receive information from, other computer 
systems and other devices in the network. In a typical network organized according to, for example, the client-server 
paradigm, certain computer systems in the network are designated as servers, which store data and programs (gen- 
erally, "information") for processing by the other, client computer systems, thereby to enable the client computer systems 
to conveniently share the information. A client computer system which needs access to information maintained by a 

45 particular server will enable the server to download the information to it over the network. After processing the data, 
the client computer system may also return the processed data to the server for storage. In addition to computer 
systems (including the above-described servers and clients), a network may also include, for example, printers and 
facsimile devices, digital audio or video storage and distribution devices, and the like, which may be shared among 
the various computer systems connected in the network/The communication links interconnecting the computer sys- 

so terns in the network may, as is conventional, comprise any convenient information -carrying medium, including wires, 
optical fibers or other media for carrying signals among the computer systems. Computer systems transfer information 
over the network by means of messages transferred over the communication links, with each message including in- 
formation and an identifier identifying the device to receive the message. 

FIG. 2 depicts a functional block diagram of functional elements of the computer system 10 depicted in FIG. 1 

55 us ful in und rstanding th invention. With reference to FIG. 2, an applications programs 21 will initiate and engage 
in a communications session ov r the network by making appropriate calls through a Windows emulator 1 7, in particular 
to the Windows socket driver constructed in accordance with the invention. The applications programs 21 are conven- 
tional applications programs which run under the Microsoft Windows operating system program ("Windows™"), and 
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th comput r syst m 10 itself, instead of running Windows, runs the well-known Unix operating system program. In 
one embodiment, the computer system 10 runs Unix with XWindows extensions (her inafter "Unix/XWindows"). The 
Windows emulator 17 also provides a Windows applications programming interface ("API") which receives Windows 
operating system calls from the Windows applications programs 21 , processes them and generates Unix/XWindows 

5 op rating system program calls as appropriat : which it provides to the UnixTXWindows operating system program 
through its API 20. The Windows emulator 17 further receives appropriate responses from the Unix/XWindows oper- 
ating system program through the API 20 : which it may process for use by the Windows applications program 21. 

The Unix operating system program provides a number of operating system services to the Windows emulator, 
as well as to Unix applications programs (not shown in FIG. 2) which may be processed by the computer system 10, 

w including those described in, for example, Kernighan and Pike, "The Unix Programming Environment", (Prentice-Hall, 
1984), and the XWindows extensions are described in a number of publications, including "The X Toolkit Intrinsics 
Reference Manual" (O'Reilly & Associates: 1990). Illustrative services provided by the operating system program in- 
clude, for example, receiving operator input from an operator input device, such as keyboard 12A or mouse 12B, for 
provision to the applications program 21 , receiving information from the applications program for display to the operator 

is and displaying it on the display device 13 in one or more windows, and retrieving data from stored on the computer 
system's storage devices tor processing by the applications program and storing processed data thereon. In addition, 
the operating system program receives network communication session calls from an applications program 21 and 
provides them to a network path 22, which to handles communications with another computer system (not shown) 
during the session, and provides responses from the network path 22, which may include data to be processed, to the 

20 applications program 21 . 

The network path 22 includes a Unix network socket driver 23, a TCP/IP stack module 24 and the network port 
14. In one embodiment, the network socket driver 23 provides network services in the form of a "socket," which is a 
well-known paradigm for facilitating communications between pairs of computer systems in a network (see, for example, 
A. Tanenbaum, Computer Networks , 2d Ed. (Prentice-Hall, 1988), pp. 434-435). A socket facilitates communications 

25 over a network between two computer systems which are connected to the network, including handling addressing, 
message buffering, message flow control, and so forth, to facilitate transfer of messages between pairs of computer 
systems for particular programs being processed by those computer systems, and provides a uniform interface to 
which TCP/IP stack modules from various manufacturers can interface. When one applications program 21 has infor- 
mation to be transferred to another applications program on another "remote" computer system, a socket arrangement 

30 will ensure that the transferring computer system will provide a message for the information which identifies the com- 
puter system as the intended recipient, and further that the message will identify the other applications program as the 
intended recipient ol the information contained in the message. 

The TCP/IP stack module 24 provides conventional TCP/IP services in connection with information provided there- 
to by the network socket driver 23 to be transmitted by the network port 14, and also in connection with messages 

35 received by the network port 1 4. The network port 1 4 transmits messages over the network communication links gen- 
erally identified by reference numeral 31 , and also receives messages from the network communication links 31 which 
were transmitted by other devices connected in the network. The network port 14 will determine from the addresses 
in the message whether the intended recipient for the message is the computer system 10, and if so it will pass the 
message to the TCP/IP stack module 24 for further handling. 

40 The WinSock socket driver 1 9 provides emulation services conforming to the specification entitled "Windows Sock- 

ets: An Open Interface For Network Programming Under Microsoft Windows™," (hereinafter the WinSock specifica- 
tion") which specifies the application programming interface ("API") for socket drivers for use in connection with Mi- 
crosoft Windows™ operating system and applications programs operating thereunder. (The WinSock specification is 
attached hereto as a Appendix A and incorporated herein by reference.) 

45 The WinSock specification defines an API which includes a number of calls based oh a Unix sockets API which 

has been popularized in the Berkeley Software Distribution ("BSD") developed by the University of California at Berkeley 
(hereinafter "basic socket calls"), with a number of additional calls (Windows "extensions") provided to allow applica- 
tions programs to have message-based, asynchronous access to a variety of network events. Services performed by 
the WinSock socket driver 19 in connection with WinSock calls include, for example, starting a socket connection to 

50 another computer system over the network, accepting a socket connection started from another computer system over 
the network, receiving data from an applications program 21 for transmission over the socket connection (corresponding 
to a "write" to the socket connection), receiving data from a socket connection for transfer to an applications program 
(corresponding to a "road" from the socket connection), selecting a socket to check its status, and closing a socket 
connection. It will be appreciated that the WinSock socket driver 1 9, in emulating at least some of the WinSock socket 

55 calls from a Windows applications program 21 , will make calls through th Unix/XWindows operating system program 
API 20, which, in turn, depending on th call, may also enable th network path 22 to perform s I cted operations. 

In accordanc with th invention the WinSock socket driver 1 9 provid s a WinSock API for Windows applications 
programs 21 which operate under th Unix operating syst m program with Xwindows extensions. Since the Unix op- 
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erating syst m program performs multi-tasking in a pre-emptive mann r, blocking in connection with a call by an ap- 
plications program op rating und r the Unix operating system program, or Unix with XWindows extensions, does not 
interf re with operations in connection with other applications programs which may be executed contemporan ously 
with th calling applications program in a multi-tasked manner. Th WinSock socket driver 19 provides emulation 

5 services in connection with th basic socket calls (that is, the calls corresponding to the socket calls as defined by 
BSD's Unix sockets API). A number of the basic socket calls defined by the BSD Unix sockets API are "blocking/ that 
is, when an applications program issues a socket call, a value is not returned to the applications program 21 until the 
operation requested in the call has been completed. A number of the socket calls may take an arbitrary period of time 
to complete. The WinSock socket driver 1 9 emulates the socket calls corresponding to the basic socket calls defined 

10 by BSD's Unix sockets API, although it performs them in a non-blocking manner. Since Windows performs multi-tasking 
in a non-pre-emptive manner, blocking in connection with a call by an applications program operating under Windows 
can interfere with operations in connection with other applications programs which may be executed contemporane- 
ously with the calling applications programs. 

In addition, the WinSock socket driver 19 provides emulation services in connection with the Windows extension 

75 operations as defined by the WinSock specification, including a number of operations which are performed which are 
analogous to the operations which are performed in response to a BSD Unix socket API call which may block, but 
which will perform the operations in a non-blocking manner. When the WinSock socket driver 19 initiates processing 
of a Windows extension operation in response to a call from an applications program 21 , it (the WinSock socket driver 
19) initially provides an acknowledgment value which operates as an asynchronous task handle, or an identifier, which 

20 identifies the operation. After receiving the call acknowledgment from the WinSock socket driver 19, the applications 
program 21 may be able to continue performing its processing operations. When the WinSock socket driver 1 9 finishes 
the operation, it provides a notification to the applications program 21 that the operation has completed, along with th 
information, if any, as requested by the call, or an error indication indicating that an error has occurred in processing 
the request. 

2S The operations performed by the WinSock socket driver 1 9 will be illustrated in connection with two WinSock calls 

which will be described in detail in connection with FIGs. 3 through 3 (CONT. C) and FIGs. 4 through 4 (CONT. C). 
Both of the calls provide information to a calling applications program as to the status of a socket connection. Generally, 
for WinSock calls which correspond to the Unix basic socket calls, the Unix/XWindows operating system API 20 is abl 
to perform operations corresponding to those provided by the WinSock calls, although perhaps in a manner which may 

30 block, using the Unix/XWindows* call processing elements, and in that case the WinSock socket driver 19 will (a) 
generate parameters for the Unix basic socket call from parameters provided in the WinSock call and, if necessary, 
other information available to it, and (b) issue the Unix basic socket call with the parameters so generated to the Unix/ 
XWindows operating system API 20 in a non-blocking manner, perhaps in a series of iterations until a required response 
is provided by the Unix/XWindows operating system API 20 or the call is cancelled by, for example, the calling appli- 
es cations program 21 , On the other hand, for W1 nSock calls which do not correspond to the Unix basic socket calls, the 
WinSock socket driver 19 will process the calls preferably without making use of Unix basic socket calls which may 
block, although it may make use of non-blocking Unix/XWindows calls. 

These will be illustrated in connection with two specific WinSock calls, namely (1 ) the WinSock Synchronous Select 
call, which is a Winsock call that corresponds to a Unix basic socket call, and (2) the WinSock Asynchronous Select, 

40 which is a WinSock Windows Extension call both of which will provide information to a calling applications program 
21 as to the current status of a socket connection or monitor the socket connection over a period of time for the oc- 
currence of selected events. As will be clear from the following, the WinSock socket driver 1 9, in executing the WinSock 
Synchronous Select call, makes use of the Unix Synchronous Select call, which under some circumstances may block, 
but the driver 19 uses the Unix Synchronous Select call in a "polling' manner to ensure that it does not block. In 

45 executing a WinSock Synchronous Select call which enables monitoring over a selected period of time, the WinSock 
socket driver 19 will make use of a non-blocking Xwindows extension call, namely, an XtAppAddTimeOut() call to the 
Unix/XWindows operating system API 20, which is described in "The X Toolkit Intrinsics Reference Manual" (OReilly 
& Associates: 1990), page 88, in Appendix B attached hereto. In response to the XlAppAddTimeOut() call, the Unix/ 
XWindows operating system API 20 will notify the WinSock socket driver 19 at the end ofa selected time interval, 

so identified in the call, following issuance of the call, which the Winsock socket driver may use to determine when the 
time period over which monitoring is to occur is to end. 

On the other hand, in executing the WinSock Asynchronous Select Call, the WinSock socket driver 19 will not 
make use of a Unix basic socket call, but will make use of a non-blocking XWindows extension call, described below 
as an XtAppAddlnput() call to the Unix/XWindows operating system API 20, which is described in "The X Toolkit In- 

55 trinsics Reference Manual" (O'Reilly & Associat s: 1990), pages 86-87, in Appendix B attached hereto. In response 
to the XtAppAddlnput() call, th Unix/XWindows op rating system API 20 notifies th WinSock socket driver 1 9 of the 
occurr nee of a particular ev nt in conn ction with the computer syst m 10 as specified in a parameter in the XtAp- 
pAddlnput(). in this case an event related to th socket connection to b monitored 
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1 . WinSock Synchronous Select: Select (rd-sock-ptr, wrt-sock-ptr, exc-sock-ptr, tm-out) 

In response to a WinSock Synchronous Select call from an applications program 21, the WinSock socket driver 
19 will monitor one or mor sockets to determine when particular type(s) of event(s) have occurred. The WinSock 
s Synchronous Select call includes a number of parameters and provides responses similar to a similarly-named Unix 
Synchronous Select call used in conn ction with the Berkeley Unix sockets as described above. In particular, the 
WinSock Synchronous Select call includes parameters including a "rd-sock-ptr" ("read socket pointer") parameter, a 
"wrt-sock-ptr" ("write socket pointer") parameter, an "exc-sock-ptr" ("exception socket pointer") parameter and a tm- 
out ("time-out") parameter. The "rd-sock-ptr" (read socket pointer) parameter comprises a pointer to a table which 

io contains identifier(s) of one or more socket(s) which the WinSock socket driver 19 is to determine is "readable," that 
is, that it has data to be provided to the applications program. Similarly, the "wrt-sock-ptr" (write socket pointer) pa- 
rameter comprises a pointer to a table which contains identifier(s) of one or more socket(s) which the WinSock socket 
driver 19 is to verify for writeability, that is, that the socket connection has been established and can accept data for 
transmission. The "exc-sock-ptr" (exception socket pointer) parameter comprises a pointer to a table which contains 

15 identifier(s) of one or more sockets which the WinSock socket driver 19 is to be checked for errors or other exception 
conditions, such as unexpected or "out-of-band" data. It will be appreciated that any of the "rd-sock-ptr" ("read socket 
pointer"), the "wrt-sock-ptr" ("write socket pointer") parameter, or the "exc-sock-ptr" ("exception socket pointer") pa- 
rameter may comprise a null value, in which case the WinSock socket driver 19 is not to perform the readability, 
writeability or error/exception checking operation, respectively for any socket. The "tm-out" ("time-out") parameter spec- 

20 jfjes the maximum amount of time the WinSock socket driver 19 will perform monitoring operations in connection with 
the identified sockets prior to providing a response. If anull value is provided for the "tm-out" parameter, the WinSock 
socket driver 19 may wait indefinitely until an event occurs in connection with one of the identified sockets. On the 
other hand, if a zero value is provided for the "tm-out* timeout parameter, the WinSock socket driver 1 9 will provide an 
immediate response, in which case the applications program 21 will essentially be using the synchronous Select call 

2S to poll the status of the socket(s) identified in the table(s) pointed to by the other parameters. 

With this background, operations performed by the WinSock socket driver 19 in connection with a WinSock Syn- 
chronous Select call will be described in connection with FIGs. 3 through 3 (CONT. C). With reference to FIG. 3, after 
receiving the WinSock Synchronous Select call, the WinSock socket driver 19 initially obtains the context or task iden- 
tifier of the current task, that is, the applications program 21 , from the operating system program (step 1 00). Thereafter, 

30 the WinSock socket driver 19 performs a number of operations to verify that is permitted to perform the operations 
required by the WinSock Synchronous Select call. Initially, the WinSock socket driver 19 will determine whether the 
socket structure has been initialized for the task identified by the task identifier by way of a Socket Start call (step 101), 
and if not, will return an error value (step 102). If the WinSock socket driver 19 makes. a positive determination in step 
101 , it will sequence to step 103 to determine whether there is an outstanding blocking operation associated with the 

35 applications program 21 (step 103), that is, an operation which must be completed before another operation can be 
performed. If the WinSock socket driver 1 9 makes a positive determination in step 103, it also will return an error value 
(step 104). 

Returning to step 103. if the WinSock socket driver 19 makes a negative determination in that step (that is, if it 
determines that there is no outstanding blocking operation for applications program 21 ), it will sequence to step 105. 

40 in that step, the WinSock socket driver 19 accesses the socket identifier table(s) which are identified by the "rd-sock- 
ptr" read socket pointer, "wrt-sock-ptr" write socket pointer and "exc-sock-ptr" exception socket pointer parameters 
and uses the socket identifiers in the table(s) to obtain the Unix file descriptor information therefor. In this operation, 
the WinSock socket driver 19 will determine whether an error is encountered in connection with the socket identifiers 
or generation of the Unix tile descriptor information (step 106), and, if so, it will return an error to the calling applications 

45 program 21 (step 107). An error may occur if, for example, the socket identifier values are outside of a selected range 
or if the calling applications program 21 does not have the right to access the socket. 

On the other hand, if the WinSock socket driver 19 determines in step 106 that no error was encountered, it will 
sequence to step 108 to determine the timeout duration, ilany, as called for by the "tm-out" timeout duration parameter 
in the WinSock Synchronous Select call. As noted above, the "tm-out" timeout duration parameter may have (i) a value 

so of zero, in which case the WinSock Synchronous Select call has a duration of zero and the call is effectively a poll of 
the sockets identified in the tables, or (ii) a non-zero value, in which case the call has a duration specified in the call, 
or alternatively (iii) a value of "null," in which case the WinSock socket driver 19 will continue monitoring until an event 
occurs or the call is cancelled. In step 108, the WinSock socket driver 19 will initially determine whether the "tm-out" 
timeout duration parameter specified a null value. If not, the WinSock socket driver 19 will determine whether the 

55 timeout vatu was zero (step 109). If the WinSock socket driv r 19 makes a negatrv determination in step 109 (that 
is, if the "tm-out" timeout duration parameter specified neither a null value nor a z ro valu ), the WinSock socket driver 
1 9 will issue an XtAppAddTimeOutQ XWindows call to the Unix/XWindows operating system API 20, providing the "tm- 
out" timeout duration parameter to the call, and will set a timer task flag (step 110). In response to the Xt AppAddTimeOut 
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() XWindows call, the timer task flag will be reset after a s lected time period. It will be appreciated that the timer task 
. flag may also b r set if the Winsock socket driver 1 9 issues an XtRemoveTimeOut() XWindows call through the Unix/ 
XWindows operating system API 20. 

After issuing the XtAppAddTimeOut() call, the WinSock socket driv r 19 will us the Unix sockets' Unix Synchro- 

5 nous Select call to determine wh n a socket identified in the table pointed to by the "rd-sock-ptr" read socket pointer 
provided in the WinSock Synchronous Select call becomes readable, a socket identified in the table pointed to by the 
"wrt-sock-ptr" write socket pointer provided in the WinSock Synchronous Select call becomes writeable, or an exception 
occurs in a socket identified in the table pointed to by the 'exc-sock-ptr" exception socket pointer provided in the 
WinSock Synchronous Select call. To provide that the Unix Synchronous Select call does not block, the WinSock socket^ 

to driver 19 will issue the Unix Synchronous Select with the "tm-out" timeout parameter set to zero (step 111). In that' 
case, the Unix Synchronous Select call will return immediately with a value identifying the total number of sockets, if 
any, which (i) are identified in the table pointed to by the -rd-sock-ptr" read socket pointer provided in the WinSock 
Synchronous Select call and are readable, or (it) are identified in the table pointed to by the "wrt-sock-ptr" write socket 
pointer provided in the WinSock Synchronous- Select call and are writeable, or (iii) for which an exception occurs in 

rs and are identified in the table pointed to by the 'exc-sock-ptr" exception socket pointer provided in the WinSock Syn- 
chronous Select call. 

After returning from the Unix Synchronous Select call the WinSock socket driver 19 will again test the "tm-out 
timeout duration parameter provided in the WinSock Synchronous Select call to determine whether it was non-zero 
(step 112) to verify that the WinSock Synchronous Select operation is not a polling operation. If the WinSock socket 

20 driver 1 9 makes a positive determination in slep 1 1 2 (thai is, the WinSock synchronous Select operation is not a poll), 
it then determines whether the value provided in response to the Unix Synchronous Select call provided a non-zero 
response value (step 113). If the WinSock socket driver 19 makes a negative determination in step 113 (that is, if th 
Unix Synchronous Select call provided a zero value), it will call a "blocking hook" function, which ensures that the 
WinSock Synchronous Select call will not block, allowing other applications the opportunity to run, and will deteymin 

2S whether (i) tho applications program 21 has terminated the WinSock Synchronous Select operation or (ii) the timer 
task flag has been cleared by the timing out of the XtAppAddTimeOut() call (step 114). Ifthe WinSock socket driver 19 
makes a negative determination in step 114, it will return to step 111 to return to the Unix Synchronous Select call. On 
the other hand, if the WinSock socket driver 19 makes a positive determination in step 1 14 (that is, ii it determines 
that the calling applications program 21 has terminated the WinSock Synchronous Select operation or that the timer 
'30 task flag has been cleared), it will terminate operations and return to the calling applications program 21 (step 115) 
The WinSock socket driver 19 will repeat the operations described above in connection with steps 111 through 
114 through a series of iterations, until it determines in step 11 4 that the calling applications program 21 has terminated 
the WinSock Synchronous Select operation or that the timer task flag has been cleared (as described above), or until 
it determines in step 112 that the Unix synchronous Select call has returned a non-zero value. If the WinSock socket 

35 driver 1 9 determines in step 1 1 2 that the Unix Synchronous Select call has returned a non-zero value, it will sequence 
to a series of steps to generate a WinSock Synchronous Select response to the applications program's WinSock Syn- 
chronous Select call. Initially, the WinSock socket driver 1 9 will issue an XtRemoveTimeOut() call to the Unix/XWindows 
operating system API 20 to cancel the XtAppAddTimeOut call (step 116) and clear the timer task flag (step 117). 
Thereafter, the WinSock socket driver 19 will identify the particular socket(s) determined to be readable, writable or 

40 for which an exception was detected (step 118), and in that operation, will convert the socket identifiers from the Unix 
file descriptor identifiers to socket identifiers. The WinSock socket driver 19 will then return to the calling applications 
program 21, providing a value corresponding to the number of sockets identified in step 116 along with the socket 
identifiers themselves (step 119). 

Returning to step 109. if the WinSock socket driver 19 determines in that step that the WinSock Synchronous 

■*s select call's "tm-out" timeout duration parameter was zero, indicating that the Synchronous Select is a poll, it will skip 
step 110 and sequence directly to step 111 to issue a Unix Synchronous Select call in the same manner as described 
above, namely, with the timeout parameter set to zero. As described above, the Unix Synchronous Select call will return 
a value identifying the total number of sockets, if any, which (i) are identified in the table pointed to by the "rd-sock-ptr" 
lead socket pointer provided in the WinSock Synchronous Select call and are readable, or (ii) are identified in the table 

50 pointed to by the "wrt-sock-ptr* write socket pointer provided in the WinSock Synchronous Select call and are writeable, 
or (iii) for which an exception occurs in and are identified in the table pointed to by the "exc-sock-ptr" exception socket 
pointer provided in the WinSock Synchronous Select call. Following the return from the Unix Synchronous Selecl call, 
the WinSock socket driver 19 will determine in step 112 that the "tm-ouf timeout duration parameter of the WinSock 
Synchronous Select call was zero, in which case it will skip steps 113 through 117 and sequence directly to step 117 

55 to clear the tim r task flag and identify the particular socket(s) determined to be readable; writable or for which an 
exc ption was detected (step 118). The WinSock socket driver 19 will then r turn to the calling applications program 
21, providing a value corr sponding to the numb r of sockets identifi d in step 111 along with the sock t identifiers 
themselves (st p 119). 
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2. Asynchronous Select: "Async Select (sock-id, win-handle, msg, ev-id)" 

In response to a WinSock Asynchronous Select call from an applications program 21 , the WinSock socket driver 
1 9, after providing the call acknowledgment to the applications program 21 , will monitor the socket identifi d by a "sock- 

s id" ("socket identifier*) parameter to determine when a particular type of network event, which is identified by parameter 
"ev-id" ("event identifier") has occurred. A number of diverse types of network events can be monitored as identified 
by the "ev-id" event identifier parameter, including a read-readiness event, a write-readiness event, an "out-of-band" 
data arrival event, an incoming network connection acceptance event, a completed network connection event and a 
connection close event. The WinSock Asynchronous Select call will provide a positive response in connection with 

10 monitoring of the various events if: 

(i) in connectbn with monitoring of a read-readiness event, if the socket identified by the "sock-id" (socket identifier) 
parameter has data to be transferred to the calling applications program 21 ; 

is (ii) in connection with monitoring of a write-readiness event, if the socket identified by the "sock-id" (socket identifier) 

parameter can receive data from the calling applications program 21 for transmission over the network port 14; 

(iii) in connection with monitoring of an out-of-band" data arrival event, i1 the socket identified by the "sock-id" 
(socket identifier) parameter has received "outof-band," or unexpected, data to be transferred to the calling ap- 

20 plications program 21 ; 

(iv) in connection with monitoring of an incoming network connection acceptance event, if the socket identified by 
the "sock-id" (socket identifier) parameter has been set up in response to a socket connection establishment re- 
quest received from another device connected to the network; 

25 

(v) in connection with monitoring of a completed network connection event, if the socket identified by the "sock- 
id" (socket identifier) parameter has been set up in response to a socket connection establishment request from 
an applications program 21 ; and 

30' (vi) in connection with monitoring of close-connection event, if the socket identified by the "sock-id" (socket iden- 

tifier) parameter has been closed. 

(While monitoring of the above-identified network events is specified in the WinSock Specification as attached hereto, 
it will be appreciated that the WinSock socket driver 1 9 may additionally or instead monitor a variety of other types of 

35 network events in connection with a WinSock Asynchronous Select call.) 

When the Winsock socket driver 19 determines that an event of the type "ev-id" has occurred, it provides a mes- 
sage, which corresponds to the "msg" ("message") parameter of the call, to a window identified by the "win-handle" 
("window handle") parameter. The window identified by the "win-handle" parameter will, in turn, normally be associated 
with the applications program 21 which issued the WinSock asynchronous Select call, in which case the provision of 

40 the message to the window identified by the "win-handle" parameter the WinSock socket driver 19 constitutes the 
required response to the applications program 21 . If the WinSock socket driver 1 9 encounters an error while executing 
the Asynchronous Select call, it will return an error value instead of the message parameter. The WinSock socket driver 
1 9 may encounter an error if it determines that, for example, no socket exists corresponding to the "sock-id" parameter, 
the applications program 21 does not have access privileges to the socket identified by the "sockHd" parameter, no 

45 event corresponds to the "ev-id" parameter, and the like. 

As will be described below in detail in connection with FIGs. 4 through 4 (CONT C), in monitoring the socket to 
determine when the required type of event has occurred, the WinSock socket driver 19 makes use various calls to the 
Unix/XWindows calls, in particular an XtAppAddtnput(), which is described in "The X Toolkit Intrinsics Reference Man- 
ual" (O'Reilly & Associates: 1990), pages 86-87, and an XtRemovelnput() call, which is described at page 301 of The 

so x Toolkit Intrinsics Reference Manual. (Pages 86- 88, 301 and 304 of The X Toolkit Intrinsics Reference Manual are 
attached hereto as Appendix B and incorporated herein by reference). 

The specific operations performed by the WinSock socket driver 19 in connection with the Asynchronous Select 
call will be described in detail in connection with tho ffow chart in FIGs. 4 through 4 (CONT. C). With reference to FIG. 
4, after receiving an Asynchronous Select call, the WinSock socket driver 1 9 initially obtains the context or task identifier 

ss of the current task, that is, the applications program 21 , from the op rating system program (step 1 30). Thereafter, the 
WinSock sock t driv r 19 perform a number of operations to verify that it can perform the op rations required by the 
Asynchronous Select call Initially, the WinSock socket driv r 1 9 will verify that the socket structure has been initialized 
for the task identified by the task identifier by way of a Socket Start call (step 1 31), and if not, will return an error value 
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(st p 132). On the other hand, if the WinSock socket driver 19 makes a positive determination in step 131. it will 
sequence to st p 1 33, in which it determin s wheth r the socket identifier "sock-id" is a valid socket identifier and if 
the applications program 21 has permission to access the socket. If the WinSock socket driver 19 makes a negative 
determination in step 133, it will return an error value (step 134). Returning to step 133. if the WinSock socket driver 

5 1 9 makes a positive determination in that step, that is, if it determines that the applications program 21 has p rmission 
to access the socket, it will sequence to step 135, in which it determines whether there is an outstanding blocking 
operation associated with the applications program 21 which has not been completed. If the WinSock socket driver 1 9 
makes a positive determination in step 1 35, it will return an error value (step 1 36). 

If the WinSock socket driver 19 makes a negative determination in step . 135, it can execute the WinSock asyn- 

10 chronous Select call issued by the applications program 21 . In that case, it will sequence to step 1 37 to clear a BLOCK- 
ING flag which it maintains in a socket information data structure. Clearing the BLOCKING flag will ensure that sub- 
sequent WinSock calls which are issued by the applications program 21 which may block, will not block while the 
WinSock Asynchronous Select call is being processed. Thereafter, the WinSock socket driver 19 determines whether 
the call is to implicitly re-enable notification for a network event (step 138) by one of the re-enabling functions as 

is described on page 90 of the WinSock specification (Appendix A attached hereto). If the WinSock socket driver 1 9 
makes a positive determination in step 1 38, it adds the type ofnetwork event for which the applications program 21 is 
to be notified to a list of network events to be monitored (step 139). On the other hand : if the WinSock socket driver 
1 9 makes a negative determination in step 1 38, it will substitute the network event identified by the "ev-id" event identifier 
parameter for the monitored network event list and issue Unix/XWindows XtRemovelnput() call(s) to the Unix/XWin- 

20 dows operating system program to enable it to stop monitoring of network events for which monitoring was previously 
enabled (step 140). 

Following step 140, the WinSock socket driver 1 9 performs a series of steps to register for monitoring of a network 
event, identified by the "ev-id - event identifier parameter, using the Unix/XWindows XtAppAddlnput() call, with the 
particular parameters of the XtAppAddlnput() call being determined by the type of event which the Asynchronous Select 

25 call requested to be monitored. The Unix/XWindows XtAppAddlnputO call provides for five parameters, including a 
context identifier, a source, a condition, a procedure identifier and client data. The context identifier identifies the context 
of the calling routine, which, in this case, corresponds to the context identifier of the applications program 21 which 
issued the Asynchronous Select call. The source parameter identifies the resource whose condition is to be monitored, 
which in this case corresponds to the socket identified by the "sock-id" socket identifier parameter obtained from the 

30 WinSock asynchronous Select call. The condition parameter identifies the condition which is to be monitored in re- 
sponse to the XtAppAddlnputO call; the XtAppAddlnput() call will return when the source has the specified condition. 
The condition parameter corresponds to the ev-id event identifier parameter of the Asynchronous Select call. The 
procedure identifier identifies the procedure to be called when the condition is satisfied, and corresponds to an identifier 
which identifies the portion of the Asynchronous Select call processing routine that is to receive the return value from 

35 the XtAppAddlnput () routine. Finally, the client data parameter identifies the data which the XtAppAddlnputO call will 
provide to the procedure identified by the procedure identifier when the condition identified by the condition identifier 
is satisfied. The client data parameter in one embodiment is a function of the socket identifier incremented by a value 
which differs among the various conditions to be monitored. 

As described above, following step 140, the WinSock socket driver 19 performs a series of steps to register for a 

40 callback using the XWindows XtAppAddlnputO call, with the particular parameters of the XtAppAddlnputO call being 
determined by the type of event which the Asynchronous Select call requested to be monitored. In particular, the 
WinSock socket driver 19 will initially determine whether the network event associated with the Asynchronous Select 
call is a socket-close event or an out-of-band data received event (step 141). In response to a positive determination 
in step 141, the WinSock socket driver 19 will generate an XtAppAddlnputO call in which the condition is specified as 

45 an XtlnputExceptMask "exception" mask (step 142). On the other hand, if the WinSock socket driver 19 makes a 
negative determination in step 141, it will sequence to step 143 to determine whether the network event associated 
with the Asynchronous Select call is a socket-accept event or a read readiness notification. In response to a positive 
determination in step 143, the WinSock socket driver 1 9 will generate an XtAppAddlnputO call in which the condition 
is specified as an XtlnputReadMask "read" mask (step 144). If the WinSock socket driver 19 makes a negative deter- 

so mination in step 143, it will sequence to step 145 to determine whether the network event associated with the Asyn- 
chronous Select call is a completed-socket-connection notification or a write-readiness notification. In response to a 
positive determination in step 145, the WinSock socket driver 19 will generate an XtAppAddlnputO call in which the 
condition is specified as an XtlnputWriteMask "write" mask (stop 146). 

Following step 142. 144 or 146. or following step 145 if the WinSock socket driver 19 makes a negative determi- 

55 nation in that step, the WinSock socket driver 1 9 returns to the applications program 21 which issued the Asynchronous 
Select call, providing a r turn value which identifies the return as an acknowl dgm nt to the Asynchronous Select call 
(step 147). 

Following step 147. the WinSock socket driver 19 will perform no further operations in connection with the Asyn- 
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chronous Select call until it receives a response from the XtAppAddlnputO call. It will be appreciated that it may perform 
operations in connection with other calls from the same or other applications programs 21 , including other Asynchro- 
nous Select calls. In addition, it may cancel the monitoring operation by the XtAppAddlnput() call by issuing an XtRem- 
ovelnput call in response to a subsequ nt Asynchronous Select call as described above in connection with step 140 
5 as described above. 

However, if the Unix/XWindows XtAppAddlnputO call provides a response to the WinSock socket driver 1 9 before 
the WinSock socket driver 19 cancels the monitoring operation, the WinSock socket driver 19 receives the response 
(step 150). Initially, the WinSock socket driver 19 will test a reentrant control flag to determine whether it is currently 
processing a response (step 151 ). If the WinSock socket driver 1 9 makes a positive determination in step 1 51 , it returns, 
to in which case it will not accept the response from the Unix/XWindows XtAppAddlnputO call at that point. The operating 
system program will attempt to provide the response to the Unix/XWindows XtAppAddlnputO call response at a later 
point. 

If the WinSock socket driver 1 9 makes a negative determination in step 1 51 , it is not currently processing a response 
to the XtAppAddlnputO call. In that case, the WinSock socket driver 19 will sequence to step 152 to condition the re-* 

*s entrant control flag to indicate that it is currently processing a response, and sequence to a series of steps to process 
the response and provide it to the applications program 21 . As described above, the response provided by the XtAp- 
pAddlnputO call corresponds to the client data parameter provided in the call itself , which in turn, identifies the type of 
socket event being monitored by the Unix/XWindows XtAppAddlnputO call. Accordingly, after receiving the response, 
the WinSock socket driver 19 will determine the type of response (step 153), and will generate a message idenfifiing 

20 the response (step 154) and post it in a response queue associated with the calling applications program 21 (step 
1 55). Thereafter, the WinSock socket driver 19 will condition the reentrant control flag to indicate that it is not currently 
processing a response, to enable it (the WinSock socket driver 1 9) to process another XtAppAddlnputO call (step 1 56). 

While the operations performed by the WinSock socket driver 19 in performing non-blocking calls defined by th 
WinSock API in connection with the Unix/XWindows operating system program have been illustrated in connection 

ss with only two WinSock calls, namely the WinSock Synchronous Select call and the WinSock Asynchronous Select call, 
it will be appreciated that it may execute other calls in a similar manner. 

The invention provides a number of advantages. In particular, it provides a WinSock socket driver 1 9 that performs 
function calls under the Unix operating system program as defined by the WinSock specification in a non-blocking 
manner, as is preferred in connection with Windows application programming. 

30 The foregoing description has been limited to a specific embodiment of this invention. It will be apparent, however, 

that various variations and modifications may be made to the invention, with the attainment of some or all of the ad- 
vantages of the invention. It is the object of the appended claims to cover these and such other variations and modi- 
fications as come within the true spirit and scope of the invention. 
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INTRODUCTION 1 

1. INTRODUCTION 

1.1 What Is Windows Sockets? 

The Windows Sockets specification defines a network programming interface for Microsoft Windows 1 
which is based on the "socket" paradigm popularized in the Berkeley Software Distribution (BSD) from 
the University of California at Berkeley. It encompasses both familiar Berkeley socket style routines and 
a set of Windows- specific extensions designed to allow the programmer to advantage of the 
message -driven nature of Windows. 

The Windows Sockets Specification is intended to provide a single API to which application developers 
can program and multiple network software vendors can conform. Furthermore, in the context of a 
particular version of Microsoft Windows, it defines a binary interface (ABO such that an application 
written to the Windows Sockets API can work with a conformant protocol implementation from any 
network software vendor. This specification thus defines the library calls and associated semantics to 
which an application developer can program and which a network software vendor can implement. 

Network software which conforms to this Windows Sockets specification will be considered "Windows 
Sockets Compliant". Suppliers of interfaces which are "Windows Sockets Compliant" be referred to 
as "Windows Sockets Suppliers'*. To be Windows Sockets Compliant, a vendor must implement 100% of 
this Windows Sockets specification. 

Applications which are capable of operating with any "Windows Sockets Compliant" protocol 
implementation will be considered as having a "Windows Sockets Interface" and will be referred to as 
"Windows Sockets Applications". 

This version of the Windows Sockets specification defines and documents the use of the API in 
conjunction with the Internet Protocol Suite (IPS. generally referred to as TCP/IP). Specifically, all 
Windows Sockets implementations support both stream (TCP) and datagram (UDP) sockets. 

While the use of this API with alternative protocol stacks is not precluded (and is expected to be the 
subject of future revisions of the specification), such usage is beyond the scope of this version of the 
specification. 

1 .2 Berkeley Sockets 

The Windows Sockets Specification has been built upon the Berkeley Sockets programming model which 
is the de facto standard for TCP/IP networking. It is intended to provide a high degree of familiarity for 
programmers who are used to programming with sockets in UNDC 2 and other environments, and to 
simplify the task of porting existing sockets-based source code. The Windows Sockets API is consistent 
with release 4 J of the Berkeley Software Distribution (4 3 BSD). 

Portions of the Windows Sockets specification are derived from material which is Copyright (c) 1982* 
1986 by the Regents of the University of California. All rights are reserved. The Berkeley Software 
License Agreement specifies the terms and conditions for redistribution. 

1 .3 Microsoft Windows and Windows-specific extensions 



1 Windows is a trademark of Microsoft Corporation. 

2 UNIX is a trademark of Unix System Laboratories. Inc. 
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This API is in tended to be usable within ail tin piemen tations and versions f Microsoft Windows from 
Microsoft Windows Version 3.0 onwards. It thus provides for Windows Sockets Lmpiementaii as and 
Windows Sockets applications in both 16 and 32 bit operating environments. 

Windows Sockets makes provisions for multithreaded Windows processes. A process contains one or 
more threads of execution. In the Windows 3. i n on -mold threaded world, a task corresponds to a process 
with a single thread. All references to threads in this document refer to actual "threads'* in multithreaded 
Windows environments. In non multithreaded environments (such as Windows 3.0). use of the term 
thread refers to a Windows process. 

The Microsoft Windows extensions included in Windows Sockets are provided to allow application 
developers to create software which conforms to the Windows programming model. It is expected that 
this will facilitate the creation of robust and high-performance applications, and will Improve the 
cooperative multitasking of applications within non-preemptive versions of Windows. With the 
exception of WSAStartupO and WSAOeanupO their use is not mandatory. 

1.4 The Status of this Specification 

Windows Sockets is an independent specification which was created and exists for the benefit of 
application developers and network vendors end. indirectly, computer users. Fj*"^ published (coo -draft) 
version of this specification represents a fully workable API for implementation by network vendors and 
programming use by application developers. Discussion of this specification and suggested improvements 
continue and are welcomed. Such discussion occurs mainly via the Internet electronic mail forum 
winsock@microdyxxe.com. Meetings of interested parties occur an an irregular basis. Details of 
meetings are publicized to the electronic mail forum. 

1.5 Revision History 

1.5.1 Windows Sockets Version 1.0 

Windows Sockets Version 1.0 represented the results of considerable work within the vendor and user 
community as di sc ussed in Appendix C. This version of the specification was released in order that 
network software suppliers and application developers could begin to construct implementations and 
applications which conformed to the Windows Sockets standard. 

1.5.2 Windows Sockets Version 1.1 

Windows Sockets Version 1.1 follows the guidelines and structure laid out by version 1.0. making 
changes only where absolutely necessary as indicated by the experiences of a number of companies that 
created Windows Sockets implementations based on the version 1.0 specification. Version 1.1 contains 
several clarifications and minor fixes to version 1.0. Additionally, the following more significant changes 
were incorporated into version 1.1: 

o fnr.lmion of the gethostnameO routine to simplify retrieval of the host's name and address. 

o Definition of DLL ordinal values below 1000 as reserved for Windows Sockets and ordinals 
above 1000 as wnrrstricwyl This allows Windows Sockets vendors to include private interfaces 
to their DLLs without risking that the ordinals chosen will conflict with a future version of 
Windows Sockets. 

o Addition of a reference count to WSAStartupO and WSACIeanupO. requiring 
correspondences between the calls. This allows applications and third- parry DLLs to make use 
of a Windows Sockets implementation without being concerned about the calls to th~<+ APIs 
made by the other. 
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o Change of return type of inet_addr() from struct in.addr to unsigned long. This was , 
required due to different handling of four-byte structure returns between the Microsoft and 
Borland C compilers. 

o Change of WSAAsyncSelectO semantics from "edge-triggered" to "level-triggered". The 
level-triggered semantics significantly simplify an application's use of this routine. 

o Change the ioctisocketO FIONBIO semantics to fail if a WSAAsyncSelectO call is 
outstanding on the socket. 

o Addition of the TCP.NODELAY socket option for RFC 1 122 conformance. 
All changes between the 1.0 and l.l specifications are flagged with change bars at the left of the page. 
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Programming with Sockets 4 

2. PROGRAMMING WITH SOCKETS 

2.1 Wind w Socket Stack In tallatlon Checking 

To detect the presence of one (or many) Windows Sockets implementations on a system, an application 
which has been Linked with the Windows Sockets Import Library may simply call the WSAStartupO 
routine. If an application wishes to be a little more sophisticated it can examine the SPATH environment 
variable and search for instances of Windows Sockets implementations (WTNSOCK.DLL), For each 
instance it can issue a LoadLibraryO call and use the WSAStartupO routine to discover implementation 
specific data. 

This version of the Windows Sockets specification does not attempt to address explicitly the issue of 
multiple concurrent Windows Sockets implementations. Nothing in the specification should be 
interpreted as restricting multiple Windows Sockets DLLs from being present and used concurrently by 
one or more Windows Sockets applications. 

For further details of where to obtain Windows Sockets components, see Appendix B.2. 

2.2 Sockets 

The following material is derived from the document "An Advanced 4.3BSD Interprocess Communication 
Tutorial" by Samuel J. Leffler. Robert S. Fabry. William N. Joy. Phil Lapsiey. Steve Miller, and Chris 
Torek. 

2.2.1 Basic concepts 

The basic building block for communication is the socket A socket is an endpoint of communication to 
which a name may be bound. Each socket in use has a type and an associated process. Sockets exist 
within communication domains. A communication domain is an abstraction introduced to bundle 
common properties of threads communicating through sockets. Sockets normally exchange data only 
with sockets in the same domain (it may be possible to cross domain boundaries, but only if some 
transladoo process is performed). The Windows Sockets facilities support a single communication 
domain: the Internet domain, which is used by processes which communicate using the Internet Protocol 
Suite. (Future versions of this specification may include additional domains.) 

Sockets are typed according to the communication properties visible to a user. Applications are 
presumed to communicate only between sockets of the same type, although there is nothing that prevents 
communication between sockets of different types should the underlying communication protocols 
support this. 

Two types of sockets currently are available to a user. A stream socket provides for the bi-directional, 
reliable, sequenced, and unduplicated flow of data without record boundaries. 

A datagram socket supports bi-directional flow of data which is not promised to be sequenced, reliable, 
or unduplicated. That is. a process receiving messages on a datagram socket may find messages 
duplicated, and. possibly, in an order different from die order in which it was sent An important 
characteristic of a datagram socket is that record boundaries in data are preserved. Datagram sockets 
closely model the facilities found in many contemporary packet switched networks such as Ethernet 

2.2.2 Client-server model 

The most commonly used paradigm in constructing distributed applications is the client/server model In 
this scheme client applications request services from a server application. This implies an asymmetry in 
establishing communication between the client and server. 
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The client and serv r require a well-known set of conventions before service may be rendered (and 
accepted). This set of conventions comprises a protocol which must be implemented at both ends of a 
connection. Depending on the situation, the protocol may be symmetric or asymmetric. In a symmetric 
protocol, either side may play the master or slave roles. In an asymmetric protocol, one side is 
imm utably recognized as the master, with the other as the slave. An example of a symmetric protocol is 
the TELNET protocol used in the Internet for remote terminal emulation. An example of an asymmetric 
protocol is the Internet file transfer protocol. FTP. No matter whether the specific protocol used in 
obtaining a service is symmetric or asymmetric, when accessing a service there is a "client process' and a 
"server process". 

A server application normally Listens at a well-known address for service requests. Thai is. the server 
process remains dormant until a connection is requested by a client s connection to the servers address. 
At such a time the server process "wakes up" and services the client, performing whatever appropriate 
actions the client requests of it. While connection-based services are the norm, some services are based 
on the use of datagram sockets. 

2,2.3 Out-of-band data - 



Note: The following discussico of out-of-band data, also referred to as TCP Urgent data, follows the 
model used in the Berkeley software distribution. Users and im pie mentors should be aware of the fact 
that there are at present two conflicting interpretations of RFC 793 (in which the concept is introduced), 
and that the implementation of out-of-band data in the Berkeley Software Distribution does not conform 
to the Host Requirements laid down in RFC 1 1 22. To minimize interoperability problems, applications 
writers are advised not to use out-of-band data unless this is required in order to ineeroperate with an 
String service. Windows Sockets suppliers are urged to document the out-of-band semantics (BSD or 
RFC 1 122) which their product implements. It is beyond the scope of this specification to m andate a 
particular set of semantics for out-of-band data handl i n g. 



The stream socket abstraction includes the notion of "exit of band" data. Out-of-band data is a logically 
independent transmission channel associated with each pair of connected stream sockets. Out-of-band 
data is delivered to the user independently of normal data. The abstraction defines that the out-of-band 
data facilities must support the reliable delivery of at least one out-of-band message at a time. This 
message may contain at least one byte of data, and at least one message may be pending delivery to the 
user at any one rime. For communications protocols which support only in- band s i g nalin g (i.e. the 
urgent data is delivered in sequence with the normal data), the system normally extracts the data from the 
normal data stream and stores it separately. This allows users to choose between receiving the urgent 
data in order and receiving it out of sequence without having to buffer all the intervening data. It is 
possible to "peek" at out-of-band data. 

An application may prefer to process out-of-band data "in-line", as part of the normal data scream. This 
is achieved by setting the socket option SO.OOBINLINE (see section 4.1.21. setsockoptO). In tnis case, 
the applk*ti<m may wish to determine whether any of the unread data u "urgent" (the term usually 
applied to in-line out-of-band data). To facilitate this, the Windows Sockets implementation will 
maintain a logical "mark" in the data stream indicate the point at which the out-of-band data was sent. 
An application can use the SIOCATMARK ioctisocketO command (see section 4.1.12) to determine 
whether there is any unread data preceding the mark. For example, it might use this to resynchronize 
with its peer by ensuring that all data up to the mark in the data stream is discarded when appropriate. 

The WSAAsyucSelectO routine is particularly well suited to handling notification of the presence of out- 
of -band-data. 

2.2.4 Broadcasting 
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By using a datagram socket, it is possible to send broadcast packets oo many networks supported by the 
system. The network itself must suppon broadcast: the system provides qo simulation of broadcast in 
software. Broadcast messages can place a high load on a network, since they force every host on the 
aetwork to service them. Consequently, the ability to send broadcast packets has been limited t sockets 
which are explicitly marked as allowing broadcasting. Broadcast is typically used for one of two reasons: 
it is desired to find a resource on a local aetwork without prior knowledge of its address, or important 
functions such as routing require that information be sent to all accessible neighbors. 

The destination address of the message to be broadcast depends on the nerwork(s) on which the message 
is to be broadcast. The Internet domain supports a shorthand notation for broadcast on the local aetwork. 
the address IN AD DR.B RO ADC AST . Received broadcast messages contain the senders address and 
port, as datagram sockets must be bound before use. 

Some types of network suppon the aodon of different types of broadcast For example, the IEEE 802.5 
token ring architecture supports the use of link-level broadcast indicators, which control whether 
broadcasts are forwarded by bridges. The Windows Sockets specification does not provide any 
mechanism whereby an application can determine the type of underlying network, nor any way to control 
the semantics of broadcasting. 

2.3 Byte Ordering 

The Intel byte ordering is like that of the DEC VAX 3 , and therefore differs from the Internet and 68000 4 - 
rype processor byte ordering. Thus care must be taken to ensure correct orientation. 

Any reference to IP addresses or port numbers passed to or from a Windows Sockets routine muse be in 
network order. This includes the IP address and port fields of a struct sockaddr.in (but not the 
sin Jamily field). 



Consider an application which normally contacts a server on the TCP port corresponding to the "rime" 
service, but which provides a m>rh>nitm for the user to specify that an alternative pen is to be used. The 
port number returned by getservbynameO is already in network order, which is the format required 
constructing an address, so no translation is required. However if the user elects to use a different port, 
entered as an integer, die application must convert this from host to network order (using the htoosO 
35 function) before using it to construct an address. Conversely, if the application wishes to display the 

number of the port within an address (returned via. e.g.. getpeeroameO). the port number must be 
converted from network to host order (using ntohsO) before it can be displayed. 

Since the Intel and Internet byte orders are different the conversions described above are unavoidable. 
40 Application writers are cautioned that they should use the standard conversion functions provided as pan 

of the Windows Sockets API rather than writing their own conversion code, since future impl ement a ti ons 
of Windows Sockets are likely to run on systems for which the host order is identical to the network byte 
order. Only applications which use the standard conversion functions are likely to be portable. 



2.4 Socket Options 

The socket options supported by Windows Sockets are listed in the pages describing setsockoptO and 
getsockoptO- A Windows Sockets implementation must recognize all of these options, and (for 
getsockoptO) return plausible values for each. The default value for each option is shown in the 
following table. 



55 



3 VAX is a trademark of Digital Equipment Corporation. 

4 68000 is a trademark of Motorola. Inc. 
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Value 


Tvpc 


Meaning 


Default 


Note* 




SO.ACCLKI CONN 


BOOL 


Socket is listenOing. 


FALSE unless a 
listeoO bas been 
performed 






SO.BROADCAST 


BOOL 


Socket is configured for ihe 


FALSE 




10 






transmission of bioadcast 










messages. 








SO DEBUG 


BOOL 


Debugging is enabled. 


FALSE 


(i) 




SO.DONTLINGER 


BOOL 


If true, the SO_LINGER option 
is disabled. 


TRUE 




15 


CO DONTROt JTR 


BOOL 


Routing is disabled. 


FALSE 


(i) 




mt 


DAtri^vr t*TTCtr cf pni< and <~l<*nr 


0 






SO KEEP ALIVE 


BOOL 


Keepaiives are being sent. 


FALSE 








crnirf linffpr 

3 U UW> l Uii^wl 

FAR * 


Re rums the current linger 
options. 






20 


SO.OOBINL1NE 


BOOL 


Out -of- band data is being 
received in the normal data 
stream. 


FALSE 






SO.RCVBUF 


int 


Buffer size for receives 


Implementation 
dependent 


(i) 




SO.REUSEADDR 


BOOL 


The address to which this socket 


FALSE 




25 






is bound can be used by others. 








SO.SNDBUF 


int 


Buffer size for sends 


Implementation 
dependent 


(i) 




SO.TYPE 


int 


The type of the socket (e.g. 
SOCKET-REAM). 


As created via 
socketO 




30 


TCP.NODELAY 


BOOL 


Disables the Nagle algorithm 
for send coalescing. 


Implementation 
dependent 





Notes: 

(0 An implementadon may silently ignore this option on setsockoptO and return a 

35 constant value for getsockoptO. or it may accept a value for setsockoptO and return the 

corresponding value in getsockoptO without using the value in any way. 



2.5 Database Files 

40 The getXbjYO 3 and WSAAsyncGetXfiy Y0 classes of routines are provided for retrieving network 

specific infonnatiocL The getXby Y0 routines were originally dp.signftd (in the first Berkeley UNDC 
releases) as mechanisms for looking up information in text databases. Although the information may be 
retrieved by the Windows Sockets implementation in different ways, a Windows Sockets application 
requests such information in a consistent manner through either the getXby Y0 or the 

45 WSAAsyncCetXByYO class of routines. 

2.6 Deviation from Berkeley Sockets 

There are a few limits instances where the Windows Sockets API has had to divert from stria adherence 
to the Berkeley conventions, usually because of difficulties of implementadon in a Windows 
50 environment. 



5 This specification uses the function name getXbjYO to represent the set of routines getbostbyaddrO. 
gelbostbynameO. etc. Similarly WSAAsyucG etX By Y0 represents WSAAsyncGetHostByAddrO. etc. 
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2.6.1 sock t data type and err r values 

A new data type. SOCKET, has been defined. The definition of this type was accessary for future 
enhancements to the Windows Sockets specification, such as being able to use sockets as fde handles Ln 
Windows NT*. Definition of rhi< type also facilitates porting of applications to a Win/32 environment, as 
the type will automatically be promoted from 16 to 32 bits. 

In UNIX, all handles, including socket handles, are small, non-negative integers, and some applications 
make assumptions that this will be true. Windows Sockets handles have no restrictions, other than that 
the value INVALID_SOCKET is not a valid socket. Socket handles may take any value in the range 0 to 
INVAUD.SOCKET- 1 . 

Because the SOCKET type is unsigned, compiling existing source code from, for example, a UNIX 
environment may lead to compiler warnings about signed/unsigned data type mism atches. 

This means, for example, that checking for errors when the socketO and acceptO routines return should 
QQt be done by comparing the return value with -1. or seeing if the value is negative (both common, and 
legal, approaches in BSD). Instead, an application should use me manifest constant INVALID.SOCKET 
as defined in winsock.h. For example: 
TYPICAL BSD STYLE: 

s - socket {...); 

if (s — -1) /• or 3 < 0 */ 

(...) 

PREFERRED STYLE: 

3 - socket (...); 
if (s »- INVALID_SOCK£T) 
(...) 

2.6.2 select() and FD_* 

Because a SOCKET is no longer represented by the UNIX-style "small non-negative integer", the 
implementation of the select 0 function was changed in me Windows Sockets APL Each set of sockets is 
still represented by the fd.set type, but instead of being stored as a bitmask the set is implemented as an 
array of SOOCETs. To avoid potential problems, applications must adhere to the use of the FD.XXX 
macros to set. initialize, clear, and check the fd.set structures. 

2.6.3 Error codes - errno, h_errno & WSAGetLastErrorO 

Error codes set by the Windows Sockets implementation are NOT made available via the errno variable. 
Additionally, for the getXbjYO class of functions, error codes are NOT made available via the h.errno 
variable. Instead, error codes are accessed by using the WSAGetLastErrorO API described in section 
4.3. 1 1 . This function is provided in Windows Sockets as a precursor (and eventually an alias) for the 
Win32 function GetLastErrorO* This is intended to provide a reliable way for a thread in a multi- 
threaded process to obtain per-thread error information. 

For compatibility with BSD. an application may choose to include a Line of the form: 
^define errno WSAGetLastErrorO 

This will allow networking code which was written to use the global errno to work correctly in a single - 
threaded environment. There are. obviously, some drawbacks. If a source file includes code which 
inspects errno for both socket and non-socket functions, this mechanism cannot be used. Furthermore, it 
is not possible for an application to assign a new value to errno. (In Windows Sockets the function 
WSASetLastErrorO may be used for this purpose.) 



6 NT and Windows/NT are trademarks of Microsoft Corporation. 
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TYPICAL BSD STYLE; 

r = recv (...); 
if (r == -1 

&£ errno ™ £ WOULD BLOCK) 
{ . . . ) 

PREFERRED STYLE: 

r - recv (...); 

i£ (r " -I /* (buc see below) •/ 

£& WSAGetLasCSrror () == EWOULDBLOCK) 

{. - - » 

Although error coos cants consistent with 4.3 Berkeley Sockets are provided for compatibility purposes, 
applications should, where possible, use the "WSA" error code definitions. For example, a more accurate 
version of the above source code fragment is: 

r - recv (...); 

if (r " -1 /* (but see below) */ 

&& WSAGetLastError 0 -= WSAEWOULDBLOCK) 
{ - . •> 

2.6.4 Pointers 

All pointers used by applications with Windows Sockets should be FAR. To facilitate this, data type 
definitions such as LPHO STENT arc provided. 



2.6.5 Renamed functions 

In two cases it was necessary to rename functions which are used in Berkeley Sockets in order to avoid 
3d clashes with other APIs. 

2.63.1 closeO & closesocketO 

In Berkeley Sockets, sockets are represented by standard file descriptors, and so the closeO function can 
be used to close sockets as well as regular flies. While nothing in the Windows Sockets API prevents an 
35 implementation from using regular file handles to identify sockets, nothing requires it either. Socket 

descriptors are not presumed to correspond to regular file handles, and file operations such as readO. 
writeO. ^ closeO cannot be assumed to work correctly when applied to sockets. Sockets must be 
closed by using the closesocketO routine. Using the closeO routine to close a socket is incorrect and the 
effects of doing so are Hnrtrfinrri by this specification. 



2.63.1 ioctIO & ioctlsocketO 

Various C language run- time systems use the ioctIO routine for purposes unrelated to Windows Sockets. 
For this reason we nave defined the routine ioctlsocketO which is used to handle socket functions which 
in the Berkeley Software Distribution are performed using ioctIO and fcntlQ* 



2.6.6 Blocking routines & EIN PROGRESS 

Although blocking operations on sockets are supported under Windows Sockets, their use is strongly 
discouraged. Programmers who are constrained to use blocking mode - for example, as pan of an 
existing application which is to be ported - should be aware of the semantics of blocking operations in 
50 Windows Sockets. See section 3. 1.1 for more details. 

4 2.6.7 Maximum number of sockets supported 

The maximum number of sockets supported by a particular Windows Sockets supplier is implementation 
specific. An application should make no assumptions about the availability of a certain number of 

55 
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sockets. This topic is addressed further in sec Don 4.3. 15. WSAStarrupO- However, independent of the 
5 number of sockets supported by a particular implementation is the issue of the maximum number of 

sockets which an application can actually make use of 

The maximum number of sockets which a Windows Sockets application can make use of is determined at 
compile time by the manifest constant FD.SETSIZE. This value is used in constructing the fd.set 

10 structures used in select 0 (see secdon 4. 1.18). The default value in winsock.h is 64. If an application is 

designed to be capable of working with more than 64 sockets, the implementor should define the 
manifest FD.SET SIZE in every source file before including winsock.h. One way of doing this may be to 
include the definition within the compiler opdons in the makefile, for example adding - 
DFD_SETSIZE= 128 as an option to the compiler command line for Microsoft C. It must be emphasized 

J5 that defining FD_SETS1ZE as a particular value has no effect on the actual number of sockets provided 

by a Windows Sockets implementation. 

2.6.8 Include files 

For ease of portability of existing Berkeley sockets based source code, a number of standard Berkeley 
include files are supported. However, these Berkeley header files merely include the winsock-h include 
fde. and it is therefore sufficient (and recommended) thai Windows Sockets applicarion source files 
should simply include winsock-h. 



20 



25 



2.6.9 Return values on API failure 

The manifest constant SOCKET.ERR0R is provided for checking API failure. Although use of this 
constant is not mandatory, it is recommended. The following example illustrates the use of the 
SOCKET_ERROR constant: 

TYPICAL BSD STYLE: 

r - recv (...); 
30 if <r — -1 /- or r < 0 */ 

&& errno ~ EWOUL0BLOCK) 
{ . . -1 

PREFERRED STYLE: 

r - recv (...); 
if (r — SOCKET^ ERROR 
55 6& WSAGetLaatError () ~ WSAEWOULDBLOCK) 

(...) 



2.6.10 Raw Sockets 

The Windows Sockets specification does not mandate that a Windows Sockets DLL support raw sockets. 
40 that is. sockets opened with SOOC.RAW. However, a Windows Sockets DLL is allowed and 

encouraged to supply raw socket support. A Windows Sockets-compliant application mat wishes to use 
raw sockets should attempt to open the socket with the socketO call (see section 4. 1.23). and if it fails 
either attempt to use another socket type or indicate the failure to the user. 



2.7 Windows Sockets In Multithreaded Versions of Windows 

The Windows Sockets interface is designed to work for both single-threaded versions of Windows (such 
as Windows 3.1) and preemptive multithreaded versions of Windows (such as Windows NT). In a 
multithreaded environment the sockets interface is basically the same, but the author of a multithreaded 
application must be aware that it is the responsibility of the application, not the Windows Sockets 
Implementation, to synchronize access to a socket between threads. This is the same rule as applies to 
other forms of I/O such as file I/O. Failure to synchronize calls on a socket leads to unpredictable results: 
for example if there are two simultaneous calls to seodO. there is no guarantee as to the order in which 
the data will be sent. 
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5 Closing a socket In one thread that has an outstanding blocking call on the same socket in another thread 
will cause the blocking call to faU with WS AELNTR. just as if the operation were canceled. This also 
applies if there is a select () call outstanding and the application closes one of the sockets being selected. 

There is no default blocking hook installed in preemptive multithreaded versions of Windows. This is 
w because the machine will not be blocked if a single application is waiting for an operation to complete 
and hence not calling PeekMessageO or GetMessageO which cause the application to yield .in 
nonpremptive Windows. However, for backwards compatibility the WSASetBlockiogHookO call is 
implemented in multithreaded versions of Windows, and any application whose behavior depends on the 
default blocking hook may install their own blocking hook which duplicates the default hook's semantics. 
is if desired. 
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3. SOCKET LIBRARY OVERVIEW 
3.1 Socket Functions 

The Windows Sockets specification includes the following Berkeley -style socket routines: 



10 


acceptO • 


An incoming connection is acknowledged and associated 
with an immediately created socket. The original socket is 
returned to the listening state. 




bindO 


Assign a local name to an unnamed socket. 


15 


closesocketO * 


Remove a socket from the per-process object reference 
table. Only blocks if SO.LINGER is set. 




coonectO * 


Initiate a connection on the specified socket. 




getpeernameO 


Retrieve the name of the peer connected to the specified 
socket. 




getsockaameO 


Retrieve the current name for the specified socket 


20 


KttsockoptO 


Retrieve options associated with the specified socket. 




btoolO 


Convert a 32-bit quantity from host byte order to network 
byte order. 




btonsO 


Convert a 16-bit quantity from host byte order to network 
byte order. 


25 


inet.addrO 


Converts a character string representing a number in the 
Internet standard ".** notation to an Internet address value. 




tnet.otoaO 


Converts an Internet address value to an ASCII string in 

QQUIIuD l.C. o.u.C.U . 




IQCUMTCKCll/ 


riyvjuc vvuuui iui t* — Kr n 


GO 


listenO 


Listen for incoming connections on a specified socket. 




otoblO 


Convert a 32-bit quantity from network byte order to host 
byte order. 




DtohsO 


Convert a 1 6- bit quantity from network byte order to host 
byte order. 


35 


recvO • 


Receive data from a connected socket. 




recvfromO • 


Receive data from either a connected or "n^^H 
socket 




selectO * 


Perform synchronous I/O multiplexing. 


I 


sendO* 


Send data to a connected socket. 


40 


sendtoO * 


Send data to either a connected or unconnected socket. 




setsockoptO 


Store options associated with die specified socket. 




shutdownO 


Shut down part of a full -duplex connection. 




socketO 


Create an endpoint for communication and return a socket. 


46 


* = The routine can block if acting on a blocking socket. 



3.1.1 BlockJng/Non blocking & Data Volatility 

One major issue in porting applications from a Berkeley sockets environment to a Windows environment 
involves "blocking**; that is. invoking a function which does not return until the associated operation is 
completed. The problem arises when die operation may take an arbitrarily long time to complete: an 
obvious example is a recvO which may block until data has been received from the peer system. The 
default behavior within the Berkeley sockets model is for a socket to operate in a blocking mode unless 
the programmer explicitly requests that operations be treated as non-blocking. It is strongly 
recommended that programmers use the nonblocking (asynchronous) operations if atoll possible* as 
they work significantly better within the nonpreemptiwe Windows environment Use blocking 
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operations only if absolutely necessary, and carefully read and understand this section if you must use 
5 blocking operations., 

Even on a blocking socket, some operations (e.g. bindO. getsockoptO. getpeernameO) can be completed 
immediately. For such operations there is no difference between blocking and non-blocking operation. 
Other operations (e.g. recvQ) may be completed immediately or may take an arbitrary time to complete. 
10 depending on various transport conditions. When applied to a blocking socket, these operations are 

referred to as blocking operations. Ail routines which can block are listed with an asterisk in the tables 
above and below. 

Within a Windows Sockets implementation, a blocking operation which cannot be completed 
75 immediately is handled as follows. The DLL initiates the operation, and then enters a loop in which it 

dispatches any Windows messages (yielding the processor to another thread if necessary ) and then checks 
for the completion of the Windows Sockets function, If the function has completed, or if 
WSACancelBlockiogCailO has been invoked, the blocking function completes with an appropriate 
result Refer to section 4.3. 13. WSASetBlockingHookO. for a complete description of this mechanism. 
20 including pseudocode for the various functions. 

If a Windows message is received for a process for which a blocking operation is in progress, there is a 
risk that the application will attempt to issue another Windows Sockets call. Because of the difficulty of 
managing this condition safely, the Windows Sockets specification does not support such application 
behavior. Two functions are provided to assist the programmer in this situation. WSAlsBtockingO may 
be called to determine whether or not a blocking Windows Sockets call is in progress. 
WSACaucelBlockingCallO may be called to cancel an in- progress blocking call, if any. Anv other 
Windows Sockets function which is callftrf in this situation will fail with the error WSAHrWROORRSS. 
It should be emphasized thai this restriction applies to both blocking and non-blocking operations. 



25 



3D 



35 



50 



Although this mechanism is sufficient for simple applications, it cannot support the complex message - 
dispatching requirements of more advanced applications (for example, those using the MDI model). For 
such applications, the Windows Sockets API includes the function WSASetBlockingHookO. which 
allows the programmer to define a special routine which will be called instead of the default message 
dispatch routine described above. 



The Windows Sockets DLL calls the blocking hook only if all of the following are true: the routine is one 
which is defined as being able to block, the specified socket is a blocking socket, and the request cannot 
be completed immediately. (A socket is set to blocking by default, but the IOCTL FIONBIO and 
WSAAsyncSelectO both set a socket to aonblockxng mode.) If an application uses only non- blocking 
40 sockets and uses the WSAAsyncSelectO and/or the WSAAsyocGetXByYO routines instead of select 0 

and the getXby YO routines, tfr*" the blocking hook will never be called and the application does not 
rj f»d to be concerned with the reentrancy issues the blocking hook can introduce. 

If an application invokes an asynchronous or non-blocking operation which takes a pointer to a memory 
45 object (e.g. a buffer, or a global variable) as an argument, it is the responsibility of the application to 

ensure that the object is available to the Windows Sockets implementation throughout the operation. The 
application must not invoke any Windows function which might affect the mapping or addressability of 
the memory involved. In a multithreaded system, the application is also responsible for coor dinatin g 
access to the object »<ing appropriate synchronization mechanisms. A Windows Sockets implementation 
cannot, and will not. address issues. The possible consequences of failing to observe these rules are 
beyond the scope of this specification. 



3.2 Database Functions 

The Windows Sockets specification defines the following database" routines. As noted earlier, a 
55 Windows Sockets supplier may choose to implement these in a manner which does not depend on local 
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database files. The pointer returned by certain database routines such as gethostbynameO points to a 
structure which is allocated by the Windows Sockets library. The data which is pointed to is volatile and 
is good only until the next Windows Sockets API call from that thread. Additionally, the application 
must never attempt to modify this structure or to free any of its components. Only one copy of this 
structure is allocated for a thread, and so the application should copy any information which it needs 
before issuing any other Windows Sockets API calls. 



gethostbyaddrO * 


Retrieve the name(s) and address corresponding to a 
network address. 


gethostbynameO * 


Retrieve the name(s) and address corresponding to a host 

nam* 


getbostnameO 


Retrieve the name of the local host. 


getprotobyoameO * 


Retrieve the protocol name and number corresponding to a 
protocol name. 


getprotobyoumberO * 


Retrieve the protocol name and number corresponding to a 
protocol number. 


getservbyoameO * 


Retrieve the service name and port corresponding to a 
service name. 


getservbyportO * 


Retrieve the service name and port corresponding to a 

port. 







* = The routine can block under some circumstances. 



3.3 Microsoft Windows-specific Extension Functions 

The Windows Sockets specification provides a number of extensions to the standard set of Berkeley 
Sockets routines. Principally, these extended APIs allow message- based, asynchronous acrw to network 
events. While use of this extended API set is not mandatory for socket- based programming (with the. 
exception of WSAStartupO and WSACIeanupO). it is recommended for conformance with the 
Microsoft Windows programming paradigm. 
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WS A A svnc GclHoslB v a riri r n 


a oi iuncuotts wuiuu provide asyncnrooous 

r^iuuiu yji LUC MJiniMHi uClKCICy 

gciAuy i V/ runcLiocLS. nor example, tne 
WSAAsyocGelHostByNameO function provides an 
asynchronous message based implementation of 
the standard Berkeley gethostbvnameO function 


WS AAsvocCetHostB rNameQ 


W^AAsvncG^tPrnfnRvNam^n 

▼ ▼ rm *JV X* I UlU U Y I ^ rl 1 1 1 f I 1 


WSAAsyncGetProtoByNumbcrO 




WSAAsvncGetServBvPortO 




Perform asynchronous version of selectO 


WS A CaacelAsy oc R eq uest 0 


Cancel an outstanding instance of a 
rvoAAsyiicueiADy xij Function. 


«J A\ alJ^C10lUUKIiI)'\ rf dllU 


tanrri an outstanding D locking API caJJ 


WSACIeanupO 


Sign off from the underlying Windows S^^ts DI J 


WSAGetLastErrorO 


Obtain details of last Windows Sockets API error 


WSAlsBIockingO 


Determine if the underlying Windows Sockets DLL is 
already blocking an existing call for this thread 


WSASetBlockingHookO 


"Hook" the blocking method used by the underlying 
Windows Sockets implementation 


WSASctLastErrorO 


Set the error to be returned by a subsequent 
WSAGetLastErrorO 


WSASUrtupO 


Initialize the underlying Windows Sockets DLL 


WSAUobookfilockineHookO 


Restore the original blocking function 



so 



55 



3.3.1 Asynchronous select() Mechanism 

The WSAAsyncSelectO API allows an application to register an interest in one or many network events. 
This API is provided to supersede the need to do polled network I/O. Any situation in which selectO or 
non-blocking I/O routines (such as sendO and rccvO) are either already used or are being considered is 
usually a candidate for the WSAAsyncSelectO API. When declaring interest in such cocdition(s). you 
supply a window handle to be used for notification. The corresponding window then receives message- 
based notification of the conditions in which you declared an interest. 

WSAAsyncSelectO allows interest to be declared in the following conditions for a particular socket: 
Socket readiness for reading 
Socket readiness for writing 
Out-of-band data ready for reading 
Socket readiness for accepting incoming connection 
Completion of nan-blocking coaaectO 
Co n ne c tion closure 

3.3.2 Asynchronous Support Routines 

The asynchraaais "database" functions allow ippiications to request information in an asynchronous 
manner. Some network implementations and/or configurations perform network based operations to 
resolve such requests. The WSAAsyncGetXBy YO functions allow application developers to request 
services which would otherwise block the operation of the whole Windows environment if the standard 
Berkeley function were used. The WSACancelAsyocRequestO function allows an application to cancel 
any outstanding asynchronous request. 

3.3.3 HookJng Blocking Methods 

As noted in section 3. 1. 1 above. Windows Sockets implements blocking operations in such a way that 
Windows message processing can continue, which may result in the application which issued the call 
receiving a Windows message. In certain situations an application may want to mfl'*»n~ or change the 
way in which this pseudo-blocking process is implemented. The WSASetBlockingHookO provides the 
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w 



15 



ability to substitute a named routine which the Windows Sockets implementation is io use when 
relinquishing the processor during a "blocking** operation. 

3.3.4 Error Handling 

For compatibility with thread-based environments, details of API errors are obtained through the 
WSACetLastErrorO API. .Although the accepted "Berkeley -Style" mechanism for obtaining socket- 
based network errors is via "errao". this mechanism cannot guarantee the integrity of an error ED in a 
multi-threaded environment. WSACetLastErrorO allows you to retrieve an error code on a per thread 
basis. 

WSACetLastErrorO returns error codes which avoid conflict with standard Microsoft C error codes. 
Certain error codes returned by certain Windows Sockets routines fall into the standard range of error 
codes as defined by Microsoft C. If you are NOT using an application development environment which 
defines error codes consistent with Microsoft C. you are advised to use the Windows Sockets error codes 
prefixed by "WSA" to ensure accurate error code detection. 

Note that this specification defines a recommended set of error codes, and lists the possible errors which 
may be returned as a result of each function. It may be the case in some implementations that other 
Windows Sockets error codes will be returned in addition to those listed, and applications should be 
prepared to handle errors other than those enumerated under each API description. However a Windows 
Sockets impkmentation must not return any value which is not enumerated in the table of legal Windows 
Sockets errors given in Appendix A. I. 

3.3.5 Accessing a Windows Sockets DLL from an Intermediate DLL 

A Windows Sockets DLL may be accessed both directly from an application and through an 
"intermediate" DLL. An example of such an intermediate DLL would be a virtual network API layer that 
supports generalized network functionality for applications and uses Windows Sockets. Such a DLL 
could be used by several applications simultaneously, and the DLL must take special precautions with 
respect to the WSAStartupO and WSACleanupO calls to ensure that these routines are called in the 
context of each task that will make Windows Sockets calls. This is because the Windows Sockets DLL 
will need a call to WSAStartupO for each task in order to set up task-specific data structures, and a call 
to WSACleanupO to free any resources allocated for the task. 

There are (at least) two ways to accomplish this. The simplest method is for the intermediate DLL to 
have calls similar to WSAStartupO and WSACleanupO that applications call as appropriate. The DLL 
would then call WSAStartupO or WSACleanupO from within these routines. Another mechanism is 
for the intermediate DLL to build a table of task handles, which are obtained from the 
CetCunrentTaskO Windows APL and at each entry point into the intermediate DLL check whether 
WSAStartupO has been called for the current task, then call WSAStartupO if necessary. 

45 If a DLL makes a blocking call and does not Install its own blocking hook, then the DLL author must be 

aware that control may be returned to the application either by an application- installed blocking hook or 
by the default blocking hook Thus, it is possible that the application will cancel the DLL's blocking 
operation via WSACancelBlockingCallO If this occurs, the DLL's blocking operadoo will fail with the 
error code WSAJEINTR. and the DLL must return control to the calling task as quickly as possible, as the 
u sed has Likely pressed a cancel or close button and the task has requested control of the CPU. It is 
recommended that DLLs which make blocking calls install their own blocking hooks with 
WSASetBlockingHookO to prevent unforeseen interactions between the application and the DLL. 
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Note that this is not necessary for DLLs in Windows NT because of its different pro cess and DLL 
structure. Under Windows NT. the intermediate DLL could simply call WSAStartupO in its DLL 
initialization routine, which is called whenever a new process which uses the DLL starts. 
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s 3.3.6 Internal use of Messages by Windows Sockets Implementations 

La order to implement Windows Sockets purely as a DLL. it may be necessary for the DLL to post 
messages internally for communication and riming. This is perfectly legal: however, a Windows Sockets 
DLL must not post messages to a window handle opened by a client application except for those 
messages requested by the application. A Windows Sockets DLL that needs to use messages for its own 
io purposes must open a hidden window and post any necessary messages to the handle for that window. 

3.3.7 Private API Interfaces 

The win sock, def file in Appendix B.7 lists the ordinals defined for the Windows Sockets APIs. In 
addition to the ordinal values listed, all ordinals 999 and below are reserved for future Windows Sockets 

,£ use. It may be convenient for a Windows Sockets implementation to export additional, private interfaces 
from the Windows Sockets DLL. This is perfectly acceptable, as long as the ordinals for these exports 
are above 1000. Note that any application that uses a particular Windows Sockets DLL's private APIs 
will most likely not work on any other vendor's Windows Sockets implementation. Only the APIs 

^ o defined in this document are guaranteed to be present in every Windows Sockets implementation. 

If an application uses private interfaces of a particular vendor's Windows Sockets DLL. it is 
recommended that the DLL not be statically linked with the application but rather dynamically loaded 
with the Windows routines LoadLibraryO and GetProcAddressO* This allows the application to give 
?5 an informative error message if it is run on a system with a Windows Sockets DLL that does not support 
the same set of extended functionality. 
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4. SOCKET LIBRARY REFERENCE 
4.1 Socket Routines 

This chapter presents the socket library routines in alphabetical order, and describes each routine in 

detail. 

In each routine it is indicated that the header fde wtnsock.h must be included. Appendix A.2 Lists the 
Berkeley-compatible header files which are supported. These are provided for compatibility purposes 
only, and each of them will simply include winsock.h. The Windows header file wtndows.b is also 
needed, but winsock.h will include it if necessary. 



so 



55 



BNSOOCIO cEP 07709S8A1 I > 



34 



EP 0 770 958 A1 

accept 19 



4.1.1 acctptO 
Description Accept a 




SOCKET PASCAL FAR eccept ( SOCKET x, struct socfciddr FAR • addr, 
let FAR •a&rUn); 



A descriptor identifying * scckei which is tingling for ennnfrrions 
after a ItstceO. 



ffj Ar An opnoaal pouuar to a buffer *hich reccirca the address of the 

rfTTir ^g W y ««H»y — twm to efaa rnwimiinirarintte Uver. The exact 
form at of (be ndd> argument is daaefsnioed by the address family 
osuMlshorf when the socket was i 



addrltn Aa optional pointer to sn aueger w hich ronf a im the length of the 

address oddr. 

Remark* This roncMexvacts the first < 
; a new socket with the I 
If no p+r^'-g < 

t as aoe>fclocking. eecepcO hiocics the caller mndi a < 
socket is marked non-frlrr ring and no pending v 

accapcO returns an error ax < ke iib a <i below. The accep te d socket any noc be used to 
t morecocnecdons. The original x 




Taearganeatoe^is a lesukpataneaw chat U filled in widiihe address of the 

j mnsity. as known id the cneaswBacaiieM layer. The exact format of timaddr 
- is flcemnrpnd by the address family m which the cnmwiwfrafioa la 
Tno e^Ur£M is s valoeHeavtt pera^ 

space pointed to by eddn on seesB tt will contain cha actual length Cn byees) 
the address raouaed. This call is used wbceeaec^ 
SOCXJSTREAM. If as^ end^er anuria* are en^ to NU^ 
about the teeaote address of the aocepaad socket is i 



Return Value Efaoezioroeam.a«eptOteawe«sJbeof type SOOCET which is a < 
thoaccepeMpackec 0&=~v^**^atrNVAJJD_$OaCET**i 
\ error code may he vtsna^d by calling WSAC etl ^afrt rrorO. 



The integer referred ua by ee^aaii^ 
oddr. Qai«*»uwiUcooe^ tfuacnulleagfctt 



Error Codec WSANOTENIT1AUSED A na.ienful WSASttrtnpO mm occur before 

Using this APL 



WSaENETOOWN The Windows J 

that the network sahsysaaa has failed. 



WSAEFAULT The addrkn argixncnt is too small fleas dun the 

r astraasockaddr). 
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WSAEINTR 

WSAEINFROGRESS 

WSAEINVAL 

WSAEMHLE 

WSAENOBUFS 

WSAENOTSOCK 

WSAEOPNOTSUPP 

WSAEWOUUD BLOCK 



The (bloc icing) call was canceled via 
WSACancelBlockingCailO. 

A blocking Windows Sockets call is in progress. 

UstenO was not invoked prior to acceptO. 

The queue is empty upon entry to accept 0 and there 
are no descriptors available. 

No buffer space is available. 

The descriptor is not a socket. 

The referenced socket is not a type that supports 
connection-oriented service. 

The socket is marked as non-blocking and no 
connections are present to be accepted. 



See Also 



bindQ. connectQ. UstenO. select 0. socketQ. WSAAsyncSeiectQ 
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4.1.2 blfid() 

Description Associate a local address with a socket. 
#include <wiosock.h> 

int PASCAL FAR bind ( SOCKET s, const struct sockaddr FAR • name, int 
namelen ); 

$ A descriptor ideatifying an unbound socket. 

name The address to assign to the socket. The sockaddr structure is defined 

as follows: 

struct sockaddr { 

u_short sa_ family; 

char sa_data [14 J ; 

\ i 

namelen The length of the name. 

Remarks This routine is u *fd on an unconnected datagram or stream socket, before subsequent 
conoectOs or listen Os. When a socket is created with socketO. it exists in a name 
space (address family), but it has no name assigned. bindO establishes the local 
association (host address/pon number) of the socket by assigning a local name to an 
unnamed socket. 

In the Internet address family, a name consists of several components. For 
SOCK_DGRAM and SOCK.STREAM, the name consists of three parts: a host address, 
the protocol number (set implicidy to UDP or TCP. respectively), and a port number 
which identifies the application. If an application does not care what address is 
assigned to iL it may specify an Internet address equal to INADDR.ANY. a port equal 
to 0. or both. If the Internet address is equal to INADDR.ANY. any appropriate 
network interface will be used: this simplifies application prograniming in the presence 
of multi-homed hosts. If the port is specified as 0, the Windows Sockets 
implementation will assign a unique port to the application with a value between 1024 
and 5000. The applicanon may use getsocknameO after bindO to learn the address that 
has been to iu but note thai getsockoameO will not necessarily fill in the 

Internet address until the socket is connected, since several Internet add r esses may be 
valid if the host is multi-homed. 

If an application desires to bind to an arbitrary port outside of the range 1024 to 5000. 
such as the case of rsh which must bind to any reserved port code similar to the 
following may be used: 

SOCKADDR_IN 3 in; 
SOCKET s; 

u_short alport - I PPORT_RE SERVED; 

3in.3in_faraily - AF_INET; 
sin . 3in — addr . s addr - 0; 
for (;;) ( 

sin.sin^port - htona (alport ) ; 

if (bind(s, (L?SOCKADDR)&3in, sizeof (sin)) 0) { 
/* it worked # / 
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if ( GetLastErrorO != WSAEADDRINUSE) { 
/• fail •/ 

alport--; 

if (alporc = = IPP0RT__R£SERVED/2 ) { 

/* fail — all unassigned reserved ports are */ 
/ * in use. * / 

} 
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Return Value If no error occurs. bindO returns 0. Otherwise, it returns SOCKET_ERROR. and a 
specific error code may be retrieved by calling WS A GetLastErrorO. 



Error Codes WSANOTTN1TIALISED 



WSAENETDOWN 



WSAEADDRINUSE 

WSAEFAULT 

WSAETNPROGRESS 
WSAEAFNOSUPPORT 

WSAEINVAL 

WSAENOBUFS 

WSAENOTSOOC 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The specified address is already in use. (See the 
SO.REUSEADDR socket option under 
setsockoptO.) 

The namelen argument is too small (less thgn the 
size of a struct sockaddr). 

A blocking Windows Sockets call is in progress. 

The speci f ie d address family is not supported by this 
protocol. 

The socket is already bound to an address. 

Not enough buffers available, too many connections. 

The descriptor is not a socket. 



See AJso 



connectO. iisteaO. getsocknameO. setsockoptO. socketO. 
WSACajKelBlockingCallO. 
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4.1.3 closesock t() 
Description Close a socket. 



w 



#include <wiosock.h> 

int PASCAL FAR closesocket ( SOCKET s ); 
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s A descriptor identifying a socket. 

Remarks This function closes a socket. More precisely, it releases the socket descriptor s, so that 

further references to s will fail with the error W S AENOTSO OC If this is the last 
reference to the underlying socket, the associated naming information and queued data 
are discarded. 

The semantics of closesock ctO are affected by the socket opdoos SO .LINGER and 
SO.DONTLINGER as follows: 
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Ontigp 



Interval 



Type of dose Wail for dose? 



SO JX) NTLINGER 

SO.UNGER 

SO_LINGER 



Don't care 

Zero 

Non-zero 



Graceful 

Hard 

Graceful 



No 
No 
Yes 



If SO_LINGER is set (i.e. the Ijonofffieid of the linger structure is non-zero; see 
sections 2.4. 4.1.7 and 4.1.21) with a zero timeout interval (IJinger is zero). 
closesocketO is not blocked even if queued data has not yet been sent or acknowledged. 
This is called a "hard" or "abortive" close, because the socket's virtual circuit is reset 
immediately, and any unseat data is lost Any recv() call on the remote side of the 
circuit will fail with WSAECONNRESET. 

If SO.UNGER is set with a non-zero timeout interval, the closesocketO call blocks 
until the remaining data has been sent or until the timeout expires. This is called a 
graceful disconnect. Note that if the socket is set to non-blocking and SO.LINGER is 
set to a non-zero timeout, the call to closesocketO will fail with an error of 
WSAEWOULDBLOOC 

If SO_DO NTLINGER is set on a stream socket (Le. the ijwoff field of the linger 
structure is zero; see sections 2.4. 4. 1.7 and 4.1.21). the closesocketO call will return 
immediately. However, any data queued for transmission will be sent if possible before 
the underlying socket is closed. This is also called a graceful disconnect. Note that in 
this case the Windows Sockets implementation may not release the socket and other 
resources for an arbitrary period, which may affect applications which expect to use all 
available sockets. 



Return Value If no error occurs. closesocketO returns 0. Otherwise, a value of SOQCET.ERROR is 
returned, and a specific error code may be retrieved by calling WSAGetLastErrorO. 

50 Error Codes WSANOnNTTTALISED A successful WSAStartupO must occur before 

lining this APL 

WSAENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

55 
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20 



25 



30 



35 



40 



45 



WSAENOTSOCK 

WSAHNPROGRESS 

WSAEINTR 

WSAEWOULDBLOCK 



The descriptor is not a socket. 

A blocking Windows Sockets call is in progress. 

The (blocking) call was canceled via 
WSACancelBlockingCallO. 

The socket is marked as non bloc king and 
SO.LINGER is set to a nonzero timeout value. 



See Also acceptQ- socketQ. ioctlsocketO. setsockoptQ. WSAAsyncSelectO. 



so 
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5 4.1.4 conn cl() 

Description Establish a coanectioo to a peer. 

^include <wiosock.h> 

iot PASCAL FAR connect ( SOCKET J, const struct sockaddr FAR • name, 
10 inl namelen ); 



s A descriptor identifying an unconnected socket. 

75 name The name of the peer to which the socket is to be connected. 

namelen The length of the name. 

Remarks This function is used to create a connection to the specified foreign association. The 
20 parameter s specifies an unconnected datagram or scream socket If the socket is 

unbound, unique values are assigned to the local association by the system, and the 
socket is marked as bound. Mote that if the address field of the name structure is all 
zeroes. conoectO will return the error WSAEADDRNOTAVAIL. 



25 



30 



For stream sockets (type SOCK.STREAM). an active connection is initiated to the 
foreign host using name (an address in the name space of the socket). When the socket 
call completes successfully, the socket is ready to send/receive data. 

For a datagram socket (type SOCK.DGRAM). a default destination is sec which will 
be used on subsequent sendO and recvO calls. 

Return Value If oo error occurs. conoectO returns 0. Otherwise, it renins SOGCET.ERROR. and a 
specific error code may be retrieved by calling WSAGetLasfJErrorO- 

35 On a blocking socket, the return value indicates success or failure of the connection 

attempt 

On a non-blocking socket if the re turn value is SOCKET.ERROR an application 
should call WS A GetJLastEnrorO. If this indicates an error code of 
40 WS AEWOULDB LOCK, then your application can either 

1 . Use select 0 to determine the completion of the connection request by checking if the 
socket is writeable. or 

2. If your application is using the message-based WSAAsyncSelectO to indicate 
45 interest in connection events, then your application will receive an FD.CONNECT 

message when the ^wwt operation is complete. 

Error Codes WS ANOTTNTTIALISED A successful WSAStartupO must occur before 

trting fhi^ APL 



50 



WSAENETDOWN The Windows Sockets implementation has detec t ed 

that the network subsystem has failed. 

WSAEADDRINUSE The specified address is already in use. 
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10 



15 



20 



25 



30 



35 



40 



45 



WSAEINTR 

WSAHNPROGRESS 
WSA£ADDRNOTAVATL 

WSAEAFNOSUPPORT 

WSAECONNREFUSED 

WSAEDESTADDREQ 

WSAEFAULT 

WSAEINVAL 

WSAHSCONN 

WSAEMFILE 

WSAENETUNREACH 

WSAJENOBUFS 

WSAENOTSOCK 
WSAFTTMEDOUT 

WSAEWOULDBLOCK 



See Also 



The (blocking) caU was canceled via 
WSACanceiBlockiogCallO. 

A blocking Windows Sockets call is in progress. 

The specified address is oot available from the local 
machine. 

Addresses in the specified family cannot be used 
with this socket. 

The attempt to connect was forcefully rejected. 

A destination address is required. 

The name ten argument is incorrect. 

The socket is not already bound to an address. 

The socket is already connected. 

No more file descriptors are available. 

The network can't be reached from this host at this 
time. 

No buffer space is available. The socket cannot be 
connected. 

The descriptor is not a socket 

Attempt to connect timed out without establishing a 
connection 

The socket is marked as non-blocking and the 
connection cannot be completed immediately. It is 
possible to selectO the socket while it is connecting 
by selectOing it for writing. 

acceptQ. bindO. getsocknameO. socketQ. selectQ and WSAAsyttcSelectO.r 
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4.1.5 g tpeernameO 

Description Get the address of the peer to which a socket is connected, 
include <winsock.h> 

int PASCAL FAR gerpeername ( SOCKET i, struct sockaddr FAR * name, iot 
FAR • namelen ); 



15 



20 



25 



name 



namelen 



A descriptor identifying a connected socket. 

The structure which is to receive the name of the peer. 

A pointer to the size of the name structure. 



Remarks getpeeroameO retrieves the name of the peer connected to the socket s and stores it in 

the struct sockaddr identified by name. It is used on a connected datagram or stream 
socket. 

On return, the namelen argument contains the actual size of the name returned in bytes. 



Return Value If no error occurs. gerpeernameO returns 0, Otherwise, a value of SOCKET.ERROR 
is returned, and a specific error code may be retrieved by calling WSAGetLastErrorQ. 



30 



35 



40 



45 



Error Codes WS ANOTTNITIALISED 

WSAENETDOWN 

WSAEFAULT 
WSAEINFROGRESS 
WSAENOTCONN 
WSAENOTSOCK 
See Also btndO. socketO. getsocknameO. 



A successful WSAStartupO must occur before 
using rh «< APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The namelen argument is not large enough. 

A blocking Windows Sockets call is in progress. 

The socket is not connected. 

The descriptor is not a socket. 
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4.1 .6 getsocknameO 

Description Get the local name for a socket. 
#inciude <wtasock.fa> 



10 



int PASCAL FAR getsockoarae ( SOCKET s, struct sockaddr FAR • name, 
int FAR • nameien ); 



75 



20 



25 



3d 



35 



40 



45 
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SS 



Remarks 



name 



name ten 



A descriptor identifying a bound socket. 
Receives the address (name) of the socket. 
The size of the name buffer. 



getsocknam eO retrieves the current name for the specified socket descriptor in name. 
It is used on a bound and/or connected socket specified by the s parameter. The local 
association is returned. This call is especially useful when a connectO call has been 
made without doing a btndO first; this call provides the only means by which you can 
determine the local association which has been set by the system. 

On re rum. the nameien argument contains the actual size of the name returned in bytes. 

If a socket was bound to IN ADD R_ ANY, indicating that any of the host's IP addresses 
should be used for the socket, getsocknameO will not necessarily return information 
about the host IP address, unless the socket has been connected with connectO or 
acceptO. A Windows Sockets application must not assume that the IP address will be 
changed from INADDR_ANY unless the socket is connected. This is because for a 
multi-homed host the IP address that will be used for the socket is unknown unless the 
socket is connected. 

Return Value If no error occurs. getsocknameO returns 0. Otherwise, a value of SOCKET ERROR 
is returned, and a specific error code may be retrieved by calling WSAGetLastErrorQ. 



Error Codes WSANOTINTTIALISED 

WSAENETDOWN 

WSAEFAULT 
WSAEINPROGRESS 

WSAENOTSOCK 
WSAHNVAL 

See Also bindQ. socketQ. gerpeemameO- 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The nameien argument is not large enough. 

A blocking Windows Sockets operation is in 
progress. 

The descriptor is not a socket. 

The socket has not been bound to an address with 
btodO. 
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4.1.7 getsock pt() 

Description Retrieve a socket option. 

^include <wiosock.h> 

lot PASCAL FAR getsockopt ( SOCKET s. int level, tot optname, 
char FAR * optval, int FAR * optien ); 

A descriptor identify Lag a socket. 

The level at which the option is defined; the only supported levels are 
SOL_SOCKET and IFPROTOJTCP. 

The socket option for which the value is to be retrieved. 

A pointer to the buffer In which the value for the requested option is 
to be returned. 

A pointer to the size of the optval buffer. 

Remarks getsockoptO retrieves the current value for a socket option associated with a socket of 

any type, in any state, and stores the result in optval. Options may exist at multiple 
protocol levels, but they are always present at the uppermost "socket" level. Options 
affect socket operations, such as whether an operation blocks or not the routing of 
packets, out -of* band data transfer, etc. 

The value associated with the selected option is returned in the buffer optval. The 
integer pointed to by optien should originally contain the size of this buffer; on return, 
it will be set to the size of the value returned. For SO.LINGER. this will be the size of 
a struct linger; for all other options it will be the size of an integer. 

If the option was never set with setsockoptOt then getsockoptO returns the default 
value for the option. 

The following options are supported for getsockoptO- The Type identifies the type of 
data addressed by optval. The TCP_NODELAY option uses level IFFROTO_TCP; all 
other options use level SOL.SOOGET. 



YaIuc 


Type 


.Mcajung 


SO.ACCEPTCOKN 


BOOL 


Socket is listeoOing. 


SO.BROADCAST 


BOOL 


Socket is configured for the transmission of 






broadcast messages. 


SO DEBUG 


BOOL 


Debugging is enabled. 


SO_DONTLINGER 


BOOL 


If true, the SO.UNGER option is disabled. 


SO.DONTROUTE 


BOOL 


Routing is disabled. 


SO_ERROR 


int 


Retrieve error status and clear. 


SO.KEEP ALIVE 


BOOL 


Keepalives are being sent. 


SO_LINGER 


struct linger 


Returns the current linger options. 




FAR* 




SO.OOBINLINE 


BOOL 


Out -of -band data is being received in the normal 






data stream. 


SO.RCVBUF 


int 


Buffer size for receives 



s 

level 

op (name 
optval 

optien 
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SO.REUSEADDR BOOL 

SO.SiNDBUF int 

SO.TYPE int 

TCP NODELAY BOOL 



The socket may be bound to an address which is 
already in use. 
Buffer size for sends 

The type of the socket (e.g. SOCK .STREAM). 
Disables the Nagle algorithm for seed coalescing. 



10 



is 



BSD op dons not supported for getsockopt 0 are: 



Value 

SO.RCVLOWAT 

SO.RCVTTMEO 

SO.SNDLOWAT 

SO.SNDTTMEO 

EP.OPT10NS 

TCP.MAXSEG 



Type 

int 

int 

int 

int 



int 



Mining 

Receive low water mark 

Receive timeout 

Send low water mark 

Send timeout 

Get options in EP header. 

Get TOP maximum segment size. 



Calling getsockoptO with an unsupported option will result in an error code of 
WS AENOPROTOOPT being returned from WSAGetLastErrorQ. 



25 

Return Value If no error occurs. getsockoptO returns 0. Otherwise, a value of SOCXET_ERROR is 
returned* and a specific error code may be retrieved by calling WSAGetLastErrorO- 



Error Codes WS ANOnNTTTALISED 

30 

WSAENETDOWN 

35 WSAEFAULT 

WSAONPROGRESS 

40 WSAENOPROTTOOPT 

45 

WSAENOTSOOC 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The optien argument was invalid. 

A blocking Windows Sockets operation is in 
progress. 

The option is unknown or unsupported. In 
particular, SO.BROADCAST is not supported on 
sockets of type SOGK.STREAM. while 
SO.ACCEFTCONN. SO.DONTUNGER. 
SO_KEEP ALIVE. SO.UNGBR and 
SO.OOB INLINE are not supported oo sockets of 
type SOOCJXJRAM. 

The descriptor is not a socket 



See Also setsockoptQ. WSAAsyncSelectQ. socketQ. 
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5 4.1.8 htonl() 

Description Convert a u Jong from host to network byte order. 

#include <winsock.h> 

w u Jong PASCAL FAR htonl ( u Jong hostlong ); 

hostlong A 32-bit number in host byte order. 

75 Remarks This routine r»k*g a 32-bit number in host byte order and returns a 32-bit number in 

network byte order. 



20 



25 



40 



45 



Return Value btoolO returns the value in network byte order. 
See AJso htoosO. ntohlQ. ntohsO- 



htons 32 



30 4.1.9 htons() 

Description Convert a u_soort from host to network byte order. 

#include <wiosock.h> 

35 u.short PASCAL FAJ* htons ( u.short hostshort ): 



hostshort A 16-bit number in host byte order. 

Remarks This routine takes a 1 6- bit number in host byte order and returns a 16-bit number in 
network byte order. 



Return Value htonsO returns the value in network byte order. 
See AJso htoalO. ntohlQ. ntohsQ. 



50 



55 



JNSDOCID <EP . 07709S8A 1 . 1 > 



47 



EP 0 770 958 A1 



inet addr 33 



4.1.10 lnet_addr() 

Description Convert a string containing a dotted address into an in .addr. 
^include <wiosock.b> 

unsigned long PASCAL FAR inet.addr ( const char FAR • cp ); 

cp A character string representing a number expressed in the Internet 

standard notation. 

Remarks This function interprets the character string specified by the cp parameter. This soring 
represents a numeric Internet address expressed in the Internet standard V notation. 
The value returned is a number suitable for use as an Internet address. Ail Internet 
addresses are returned in network order (bytes ordered from left to right). 

Interact Addresses 

Values specified using the "." notation take one of the following forms: 
a.b.c.d a.b.c a.b a 

When four parts are specified, each is interpreted as a byte of data and assigned, from 
left to right, to the four bytes of an Internet address. Note mat when an Internet address 
is viewed as a 32- bit integer quantity on the Intel architecture, the bytes referred to 
above appear as "d.c.b.a\ That is. the bytes on an Intel processor are ordered from 
right to left. 

Note: The following notations are only used by Berkeley, and nowhere else on the 
Internet. In the interests of compatibility with their software, they are supported as 
specified. 

When a three part address is specified, the last part is interpreted as a 16-bit quantity 
and placed in the right most two bytes of the network address. This makes the three 
part address format convenient for specifying Class B network addresses as 
"128-nechost". 

When a two part address is specified, the last part is interpreted as a 24-bit quantity and 
placed in the right most three bytes of the network address. This makes the two part 
address format convenient for specifying Class A network addresses as "net .host". 

When only one part is given, the value is stored direcdy in the network address without 
any byte rearrangement 

Return Value If no error occurs. inet.addrO returns an unsigned long containing a suitable binary 
represen tad on of the Internet address given. If the passed-in soring does not contain a 
legitimate Internet address, for example if a portion of an "a.b.c.d " address exceeds 255. 
inet.addrO returns the value INADDR.NONE. 

See AJ so inet.atoaQ 
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4.1.11 lnet_ntoa() 

Description Convert a network address into a string in dotted format, 
^include <winsock.h> 

char FAR * PASCAL FAR inet_ntoa ( struct io.addr in ); 



75 



20 



in 



A structure which represents an Internet host address. 



Remarks This function takes an Internet address structure specified by the in parameter. It 

returns an ASCII string representing the address in "." notation as "a.b.c.d". Note that 
the string returned by inet.ntoaO resides in memory which is allocated by the 
Windows Sockets implementation. The application should not make any assumptions 
about the way in which the memory is allocated. The data is guaranteed to be valid 
until the next Windows Sockets API call within the same thread, but no longer. 



2$ 



Return Value If no error occurs. inet.ntoaO returns a char pointer to a static buffer containing the 
text address in standard V notation. Otherwise, it returns NULL. The data should be 
copied before another Windows Sockets call is made. 

See Also inet.addrQ. 
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4.1.12 loctlsocket() 

Description Control the mode of a socket. 



10 



^include <wiosock.h> 

iot PASCAL FAR ioctisocket ( SOCKET s t long cmd, ujoog FAR • argp ); 



15 



20 



25 



cmd 



argp 



A descriptor identifying a socket. 

The command to perform on the socket s. 

A pointer to a parameter for cmd. 



Remarks This routine may be used on any socket in any state. It is used to get or retrieve 
operating parameters associated with the socket, independent of the protocol and 
communications subsystem. The follow Lag commands are supported: 



rnmmand 



femaaacji 
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35 



40 



45 



50 



FIONBIO Enable or disable aon-blocking mode on the socket s. argp points at 

an unsigned long, which Is non-zero if non- blocking mode is to be 
enabled and zero if it is to be disabled. When a socket is created, it 
operates in blocking mode (i.e. non- blocking mode is disabled). This 
is consis t ent with BSD sockets. 

The WSAAsyncSelectO routine automatically sets a socket to 
nonbiocking mode. If WSAAsyncSelectO has been issued on a 
socket, then any attempt to use ioctlsocketO to set the socket back to 
blocking mode will fail with WSAEINVAL. To set the socket back to 
bl ockin g mode, an application must first disable WSAAsyncSelectO 
by calling WSAAsyncSelectO with the lEvcni parameter equal to 0. 

FIONREAD Determine the amount of data which can be read atomicaily from 
socket s. argp points at an unsigned long in which ioctlsocketO 
stores the result. If s is of type SOCK.STREAM, FIONREAD returns 
the total amount of data which may be read in a single recvO; this is 
normally the same as the total amount of data queued on the socket. 
If j is of type SOCK JXJRAM. FIONREAD returns the si2e of the 
first datagram queued on the socket 

SIOCATMARK Determine whether or not all out-of-band data has been read. This 
applies only to a socket of type SOCK.STREAM which has been 
configured for in* line reception of any out-of-band data 
(SO^OOB INLINE). If no out-of-band data is waiting u> be read, the 
operation returns TRUE. Otherwise it returns FALSE, and the next 
rccvO or rccvfromO performed on the socket will retrieve some or all 
of the data preceding the "mark"; the application should use the 
SIOCATMARK operation to determine whether any remains. If there 
is any normal data preceding the "urgent" (out of band) data, it will be 
received in order. (Note that a recvO or rccvfromO will never miir 
out-of-band and normal data in the same call.) argp points at a 
BOOL in which ioctlsocketO stores the result. 
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Compatibility This functioa is a subset of iocUO as used in Berkeley sockets. In particular, there is no 
command which is equivalent to FIOASYNC. while SIOCATMARK is the only socket- 
level command which is supported. 

10 

Return Value Upon successful completion, the ioctlsocketO returns 0. Otherwise, a value of 

SOCKET_ERROR is returned, and a specific error code may be retrieved by calling 
WSAGetLastErrorO. 

is Error Codes WSANOnNTTIALISED 



WSAENFTDOWN 

20 

WSAHNVAL 



WSAQNPROGRESS 



WSAENOTSOCK 

30 

See Also socketO. setsockoptO. getsockoptO. WSAAsyncSelectO- 
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A successful WSAStartupO must occur before 

tiding rhL< API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

cmd is not a valid command, or argp is not an 
acceptable parameter for cmd. or the command is 
not applicable to the type of socket supplied 

A blocking Windows Sockets operation is in 
progress. 

The descriptor s is not a socket. 
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4.1.13 list n() 

Description Establish a socket to Listen for incoming connection, 
^include <wiasock.b> 

int PASCAL FAR listen ( SOCKET s, int backlog ); 

s A descriptor identifying a bound, unconnected socket. 

backlog The maximum length to which the queue of pending connections may 

grow. 

Remarks To accept connections, a socket is first created with socketO. a backlog for incoming 
connections is specified with listen 0. and then the connections are accepted with 
acceptO. UstenO applies only to sockets that support connections, i.e. chose of type 
SOCK_STREAM. The socket s is put into "passive" mode where incoming connections 
are acknowledged and queued pending acceptance by the process. 

This function is typically used by servers that could have more than one connection 
request at a time: if a connection request arrives with the queue full, the client will 
receive an error with an indication of WS AECONNREFUSED. 

listen 0 attempts to continue to function rationally when there are no available 
descriptors. It will accept connections until the queue is emptied. If descriptors 
become available, a later call to list en 0 or acceptO will re-fill the queue to the current 
or most recent "backlog", if possible, and resume listening for incoming connections. 

Compatibility backlog is currently limited (silently) to 5. As in 4.3BSD. illegal values (less than 1 or 
greater than 5) are replaced by the nearest legal value. 

Return Value If no error occurs. UstenO returns 0. Otherwise, a value of SOCKET_ERROR is 

returned, and a specific error code may be retrieved by falling WSAGetLastErrorQ. 
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Error Codes WS ANOnNTTIAL ISED 

WSAENETDOWN 

WSAEADDRJNUSE 

WSAHNFROGRESS 

WSAHNVAL 

WSAOSCONN 

WSAEMRLE 

WSAENOBUFS 



A successful WSAStartupO must occur before 

»<ing thie API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

An attempt has been made to UstenO on an address 
in use. 

A blocking Windows Sockets operation is in 
progress. 

The socket has not been bound with bindO or is 
already connected. 

The socket is already connected. 

No more file descriptors axe available. 

N buffer space is available. 



BNSOOCID <EP 0770958A1 I > 



52 



EP 0 770 958 A1 



listen 38 



10 



See Also 



WSAENOTSOCK 
WSAEOPNOTSUPP 

acceptQ. coonectO. sockctO- 



The descriptor is not a socket. 

The referenced socket is not of a type that supports 
the listen 0 operation. 
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4.1.14 ntohl() 

Description Convert a ujoog from network to host byte order, 
^include <winsock.h> 

ujong PASCAL FAR otohl ( ujoog nettong ); 



Remarks 



net long 



A 32-bit number in network byte order. 



This routine takes a 32-bit number in network byte order and returns a 32-bit number in 
host byte order. 



35 



Return Value otoblO returns the value In host byte order. 
See Also htonlO. btonsO. atohsO 
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ntohs 40 

4.1.15 ntohs() 

Description Convert a u_sbort from network to host byte order, 
^include <wiosock.h> 

u_short PASCAL FAR ntohs ( u_short neuhort ); 

netshnrt A 1 6-bit number La network byte order. 

Remarks This routine takes a 16-bit number in network byte order and returns a 16-bit number in 

host bvte order. 



2 0 Return Value ntohsO returns the value in host byte order. 
See Also htonlO. htonsQ. ntohlQ 
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4.1.16 recv() 

Description Receive data from a socket. 

^include <wins<Kk.h> 

int PASCAL FAR recv ( SOCKET s. char FAR * buf. int ten. int fla^s ): 

5 A descriptor identifying a connected socket. 

£u/ A buffer for the incoming data. 

icn The length of buf. 

flags Specifies the way La which the call is made. 

Remarks This function is used on connected datagram or stream sockets specified by the s 

parameter and is used to read incoming data. 

For sockets of rype SOCK_STR£AM. as much information as is currendy available up 
to the size of the buffer supplied is returned. If the socket has been configured for La- 
Line reception of out-of-band data (socket option SO.OOBINUNE) and out-of-band 
data is unread, only out-of-band data will be returned. The application may use the 
ioctlsocketO S 10 C ATMARK to determine whether any more out-of-band data remains 
to be read. 

For datagram sockets, data is extracted from the first enqueued datagram, up to the size 
of the buffer supplied. Lf the datagram is larger than the buffer supplied, the buffer is 
filled with the first part of the datagram, the excess data is lost, and recvO returns the 
error WSAEMSGSEZE. 

If do incoming data is available at the socket, the recvQ call waits for data to arrive 
unless the socket is n on- blocking. In this case a value of SOCKET^ ERROR is returned 
with the error code set to WS AEWOULDBLOCK. Toe selectO or WSAAsyrjcSelectQ 
calls may be used to determine when more cata arrives. 

If the socket is of type S 0CK_STR£AM and the remote side has shut down the 
connection gracefully, a recvQ will complete immediately with 0 bytes received. If the 
connection has been reset, a recvO will fail with the error WSAECONNRJESET. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is. the semantics of this function are 
determined by the socket options and the flags parameter. The latter is coos true ted by 
or-ing any of the following values: 

Value Vfraniny 

MSG_PEEK Peek at the incoming data. The data is copied into the buffer but is 
not removed from the input queue. 

MSG_OOB Process out-of-band data (See <^ctioa 2.2.3 for a discussion of mis 
topic.) 
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Return Value If no error occurs. recv() returns the number of bytes received. If the connection has 
been closed, it returns 0. Otherwise, a value of SOCKET.ERROR is rerumed. and a 
specific error code may be retrieved by calling WSACetLastErrorO. 



Error Cedes W S AJS'OTTNTTIAL IS ED 

WSAENETDOWN 

WSAENOTCON7* 
WS AETNTR 

WSAHNPROGRESS 

WSAENOTSOCX 
WSAEOPNOTSUPP 

WS AES HUTDO WN 

WSAEWOUT-DBLOCK 

WSAEMSGSIZE 

WSAETNVAL 
WSAECONN ABORTED 

WSAECONNRESET 



A successful WSAStartupO must occur before 
using thi<: API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The socket is not connected. 

The (bloc long) call was canceled via 
WSACancelBlockingCaJJO. 

A blocking W*indows Sockets operation is in 
progress. 

The descriptor is not a socket. 

MSG.OOB was specified, but the socket is not of 
rype SOCX_STREAM. 

The socket has been shutdown; it is not possible to 
recvO on a socket after shutdownO has been 
invoked with how set to 0 or 2. 

The socket is marked as non-blocking and the 
receive operation would block. 

The datagram was too large to fit into the specified 
buffer and was truncated. 

The socket has not been bound with biodO- 

The virtual circuit was aborted due to timeout or 
other failure. 

The virtual circuit was reset by the remote side. 



See AJso recvfromO. readQ. .recvQ, seodQ. selectQ. WSAAsyncSelectQ. socketO 



so 
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4.1.17 recvfromf) 

Description Receive a datagram and store the source address, 
^include <wiusock.h> 

int PASCAL FAR recvfrom ( SOCKET y. char FAR • oaf. int ten, int jligs. 
struct sock add r FAR • from, int FAR ■ fromlen ); 



J A descriptor identifying a bound socket. 

buf A buffer for the incoming data. 

len The length of buf 

fags Specifies the way in which the call is made. 

from Ad optional pointer to a buffer which will hold the source address 
upon re rum. 

fromlen An optional pointer to the size of the from buffer. 



Remarks This function is used to read incoming data on a (possibly connected) socket and 

capture the address from which the data was sent. 

For sockets of type SOCK_STREAM. as much inform a don as is currently available up 
to the size of the buffer supplied is returned- If the socket has been configured for in- 
line reception of out-of-band data (socket option SO.OOBINIJNE) and out -of- band 
data is unread, only out-of-band data will be returned. The application may use the 
ioctisocketO SIOCATMARK to determine whether any more out-of-band data remains 
to be read. The from and fromlen parameters are ignored for SOCK_STR£AM sockets. 

For datagram sockets, data is extracted from the first enqueued datagram, up to the size 
of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is 
filled with the first part of the message, the excess data is lost, and recvfromO returns 
the error code WSAEMSGSEZE. 

U from is non-zero, and the socket is of type SOCK.DGRAM. the network address of 
the peer which sent the data is copied to the corresponding struct sockaddr. The value 
pointed to by fromlen is initialized to the size of this structure, and is modified on return 
to indicate the actual size of the address stored there. 

If no incoming data is available at the socket, the recvfromO call waits for data to 
arrive unless the socket is qoq- blocking. In this case a value of SOCKET_ER_ROR is 
returned with the error code set to WSAEW OULDBLOCK. The seJectO or 
WSAAsyncSelectO calls may be used to determine when more data arrives. 

If the socket is of type S OCX _ STREAM and the remote side has shut down the 
connection gracefully, a recvfromO will complete immediately with 0 bytes received. 
If the connection has been reset recvO will fail with the error WSAECONNRESET. 

Fla%s may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is. the semantics of this function are 
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determined by the socket options and the fla>s parameter. The Utter is constructed bv 
or-LDg any of the following values: 



Value 



10 



■ Meaning 



MSG_PEEK. Peek at the incoming data. The data is copied into the buffer but is 
QOt removed from the input queue. 

MSG JX)B Process out-of-band data (See section 2.2.3 for a discussion of this 
topic.) 
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30 



35 



Return Value If no error occurs, rccvfromO returns the number of bytes received. If the connection 
has been closed, it returns 0. Otherwise, a value of SOCK£T_ERROR is returned, and 
a specific error code may be retrieved by calling WSAGetLastErrorO- 



40 
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SO 



Error Codes W S ANOTTNTTIALIS ED 

WSAENFTOOWN 

WSAEFAULT 

WSAEINTR 

WSAETNPROGRESS 

WSAEINVAL 
WSAENOTCONN 

WSAENOTSOCK 
WSAEOPNOTSUPP 

WSAESHl/TDOWN 

WSAEWOULDBLOCK 

WSAEMSGSrZE 

WS AECON*N ABORTED 
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A successful VVSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The fromlen argument was invalid: the from buffer 
was too small to accommodate the peer address. 

The (blocking) call was canceled via 
WSACancelBlockingCaUO. 

A blocking Windows Sockets operation is in 
progress. 

The socket has not been bound with blndO 

The socket is not connected (SOGK_STREAM 
only). 

The descriptor is not a socket. 

MSG.OOB was specified, but the socket is not of 
type SOCK _STRJEAM 

The socket has been shutdown; it is not possible to 
recvfromO on a socket after sfautdownO has been 
invoked with how set to 0 or 2. 

The socket is marked as non-blocking and the 
recvfromO operation would block. 

The datagram was too large to fit into the specified 
buffer and was truncated. 

The virtual circuit was aborted due to dmeout or 
other failure. 
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W S AEC O .VNRES ET The virruai circuit was reset by the remote side. 

See Also recvQ, sendQ. sockelQ. WS A A sync Select*) 
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4.1.18 select() 

Descrlptl n Determine the status of one or more sockets, waiting Li Qecessary . 
-include <winsock.h> 

int PASCAL FAR select ( int nfds. fd.set FAR • readfds, fd.set FAR • write fds % 
fd_set FaR • exceptfds, const struct LimevaJ FAR " timeout ); 



nfds This argument is ignored and included ooJy for the sake of 

compatibility. 

readfds An optional pointer to a set of sockets to be checked for readability. 

write/ds An opdoaaJ pointer to a set of sockets to be checked for writabLiity 

exceptfds An optional pointer to a set of sockets co be checked for errors. 

timeout The maximum time for selectO to wait, or NULL for blocking 

operation. 



Remarks This function is used to determine the status of one or more sockets. For each socket. 

the caller may request information on read, write or error status. The set of sockets for 
which a given status is requested is indicated by an fd_set structure. Upon return, the 
structure is updated to reflect the subset of these sockets which meet the specified 
condition, and selectO returns the number of sockets meeting the conditions. A set of 
macros is provided for manipulating an fd_seL These macros are compatible with those 
used in the Berkeley software, but the underlying representation is completely different. 

The parameter readfds identifies those sockets which are to be checked for readability. 
If the socket is currently listenOuig. it will be marked as readable if an incoming 
connection request has been received, so that an accept 0 is guaranteed to complete 
without blocking. For other sockets, readability means that queued data is available for 
reading or. for sockets of type SOCK.STREAM. that the virtual socket corresponding 
to the socket has been closed, so that a recvO or recvfrooiO is guaranteed to complete 
without blocking. If the virtual circuit was closed gracefully, then a recvO will return 
immediately with 0 bytes read: if the virtual circuit was reset, then a recvO will 
complete immediately with the error code WSAECONNRESET. The presence of out- 
of-band data will be checked if the socket option SO_OOB INLINE has been enabled 
(see setsockoptO). 

The parameter write fds identifies those sockets which are to be checked for wri Lability. 
If a socket is coonectOing (noo- blocking), wri lability means that the connection 
establishment successfully completed. If the socket is not in the process of 
coaoectOing. wntability means that a sendO or sendtoO will complete without 
blocking. [It is not specified how long this guarantee can be assumed to be valid, 
particularly in a multithreaded environment] 

The parameter exceptfds identifies those sockets which are to be checked for the 
presence of out-of-band data or any exceptional error coodinons. Note that out-of -band 
data will only be reported in this way if the option SO.OOBtNLTNE is FALSE. For a 
SOCK_STR£AM. the breaking of the connection by the peer or due to KEEP .ALIVE 
failure will be indicated as an exception. This specification does not define which other 
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Return Value 



errors w*il be included. It a socket is connectOing ( con- bloc Icing), failure of the 
connect attempt is indicated in exceptt'ds. 

Any of renufJs. ^ntefds, or exceptfds ciiay be given as NULL if no descriptors are of 
Latere si. 

Four macros are defined in the header file winsock.h for manipulating the- descriptor 
sets. The variable FD_.SETS[ZE determines the maximum number of descriptors in a 
set. (The default value of FD_SETSIZE is 64. which may be modified by ^defining 
FD_ SET SIZE to another value before ^including winsock.h.) Internally, an fd_set Ls 
represented as an array of SOCKETs; the last valid entry is followed by an element set 
to INV.\LID_SOCKFT. The macros are: 



FD_CLRU, *set) 
FDJSSET(5, m set) 
FD_SET(j, 'set) 
FD_ZERO(-j<rr) 



Removes the descriptor s from set. 

Nonzero Lf s is a member of the set. zero otherwise. 

Adds descriptor s to set. 

Initializes the set to the NULL set. 



The parameter timeout controls how long the selectO may take to complete. If timeout 
is a null pointer. selectO will block ld definitely until at least one descriptor meets the 
specified criteria. Otherwise, timeout points to a struct timeval which specifies the 
maximum time that selectO should wait before re turning. If the timevaJ is initialized to 
(0. 0 1. selectO W ^U return immediately; this is used to "poll" the state of the selected 
sockets. If this ts the case, then the selectO call is considered nonlocking and the 
standard assumptions for aonblocldng calls apply. For example, the blocking hook 
must not be called, and the Windows Sockets implementation must not yield. 

selectO returns the total number of descriptors which are ready and contained in the 
fd_set structures. 0 if the time limit expired, or SOCKET_ERROR if an error occurred. 
If the return value is SOCKET. ERROR. WSAGetLastErrorO may be used to retrieve 
a specific error code. 



Error Codes WS ANOTTNTTTAL IS ED 



WSAENETDOWN 



WSAE3NVAL 



WSAHTNTR 



WSAEINFROGRESS 



so 



A successful WSASlartupO must occur before 

n<ing f hi- API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The timeout value is not valid. 

The (blocking} call was canceled via 
WSACancelBlockiogCallO. 

A blocking Windows Sockets operation is in 
progress. 



One of the descriptor sets contains an entry which is 
not a socket 



See Also 



WSAENOTSOOC 
WSAAsyocSelectQ. acceptQ. coocectO recvQ. recvfromO. seiidQ 
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4.1.19 send<) 

Description Send data on a connected socket, 
"include <winsock.h> 

int PASCAL FAR send ( SOCKET s. const char FAR • buf. int ten. tat j!a%s ): 

5 A descriptor identify ing 3 connected socket. 

b u f A buffer containing the data to be transmitted. 

ten The length of the data in buf. 

flags Specifies the way in which the call is made. 

Remarks sendO is used on connected datagram or stream sockets and is used to write outgoing 

data on a socket. For datagram sockets, care must be taken not to exceed the maximum 
IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in 
the WSAData structure returned by WSAStarrupO If the data is too long to pass 
atomic ally through the underlying protocol the error WSAEMSGSEZE is returned, and 
no data is transmitted. 

Note that the successful completion of a seodO does not indicate that the data was 
successfully delivered. 

If no buffer space is available within the transport system to hold the data to be 
transmitted. sendO will block unless the socket has been placed in a non-blocking I/O 
mode. On non-blocking SOCK_STRJEAM sockets, the number of bytes written may be 
between 1 and the requested length, depending on buffer availability on both the local 
and foreign hosts. The selectO call may be used to determine when it is possible to 
send more data. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is. the semantics of this function are 
determined by the socket options and the flags parameter. The latter is constructed by 
or- ing any of the following values: 

Value Mining 

MSG_DO NTROUTE 

Specifies that the data should not be subject to routing. A Windows 
Sockets supplier may choose 10 ignore this flag: see also (he 
discussion of the SO_DONTROUTE opdon in section 2.4. 

MSG_OOB Send out-of-band data (SOCK .STREAM only: see also section 2.2.3) 

Return Value If no error occurs. seodQ returns the total number of characters sent. (Note that this 
may be less *han the number indicated by len.) Otherwise, a value of 
SOCKET.ERROR is returned, and a specific error code may be retrieved by calling 
WS A GetLastErrorO. 
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Error Codes W S AN OT INITIALISED 

WSAENFTDOWN 

WSAEACCES 

WSAEINTR 

W S AEHSTROGRESS 

WSAEFAULT 

WSAENETRESET 

WSAENOBUFS 

WSAENOTCOIVN 
WSAENOTSOCK 
WSAEOPNOTSUFP 

WSAESrRTTDOWN 

WS AEWOULDB LOCK 
WSAEMSGSEE 

WSAETNVAL 
WSAECO NN ABORTED 

WSAECONNRESET 



A successful WSAStamip() caust occui befoi^ 
n^ ing this API. 

The Windows Sockets implementation has detected 
that Lhe Qecwork subsystem has failed. 

The requested address is a broadcast address, but the 
appropriate flag was not set. 

The (blocking) call was canceled via 
WSACancelBlockingCallO. 

A blocking Windows Sockets operation is in 
progress. 

The buf argument is doc in a valid part of Lhe user 
address space. 

The connection must be reset because the Windows 
Sockets implementation dropped it. 

Toe Windows Sockets implementation reports a 
buffer deadlock. 

The socket is not connected. 

The descriptor is not a socket. 

MSG.OOB was specified, but the socket is not of 
type SOCK_STREAM. 

The socket has been shutdown: it is not possible to 
seodO on a socket after shutdownO has been 
invoked with how set to I or 2. 

The socket is marked as non-blocking and the 
requested operation would block. 

The socket is of type SOOC.DGRAM. and the 
datagram Is larger than the maximum supported by 
the Windows Sockets implementation. 

The socket has not been bound with biodO. 

The virtual circuit was aborted due to timeout or 
other failure. 

The virtual circuit was reset by the remote side 



See Also 



recvQ. recvfromO. socketQ. sendtoQ. WSAStarmpO. 
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4.1.20 sendto() 

Description Scad data to a specific destination, 
-include <winsock.h> 

int PASCAL FAR sendto ( SOCKET s. const char FAR * bu/\ int ten, int flags. 
const struct sockaddr FAR • to, int tolen ); 



s 


A descriptor identifying a socket. 


buf 


A buffer containing the data to be transmitted. 


len 


The length of the data in buf. 


flags 


Specifies the way in which the coil is made. 


to 


An optional pointer to the address of the target socket. 


to len 


The size of the address in to. 



Remarks seodtoO is used on datagram or stream sockets and is used to write outgoing data on a 
socket. For datagram sockets, care must be taken not to exceed the maximum IP packet 
size of the underlying subnets, which is given by the iMaxUdpDg element in the 
WSADau structure returned by WSAStartupO. If the data is too long to pass 
a tnm ir ally thro ugh the underlying protocol the error WS AEMSGS r/.h. is returned, and 
no data is transmitted. 

Note that the successful completion of a scud to 0 does not indicate that the data was 
successfully delivered. 

sendtoO is normally used on a SOCK.DGRAM socket to send a datagram to a specific 
peer socket identified by the to parameter. On a SOGK.STREAM socket, the to and 
tolen parameters are ignored; in this case the seodtoO is equivalent to sendO. 

To send a broadcast (on a SOCK.DGRAM only), the address in the to parameter should 
be constructed using the special IP address INADDR_BROADCAST (defined in 
winsockJi) together with the intended port number. It is generally inadvisable for a 
broadcast datagram to exceed the size at which fragmentation may occur, which implies 
that the data portion of the datagram (excluding headers) should not exceed 512 bytes. 

If no buffer space is available within the transport system to bold the data to be 
transmitted. seodtoO will block unless the socket has been placed in a non-blocking I/O 
mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be 
between 1 and the requested length, depending on buffer availability on both the local 
and foreign hosts. The selectQ call may be used to determine when it is possible to 
send more data. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is. the semantics of mis function are 
determined by the socket opticas and the flags parameter. The lane/ is constructed by 
or-ing any of the following values: 
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MSG.DONTROLTE 

Specifies that the da La should no< be subject to routing. A Windows 
Sockets supplier may choose to ignore this flag: see aJso the 
discuss ioo of the SO.DONTROLTE option in section . 



M5G.OOB 



Send oui-of-band data (SOCK_ STREAM only: see also section ) 



15 



Return Value I: no error occurs. sendtoQ returns the total number of characters sent. (Note thai this 
may be less than ldc number indicated by ten.) Otherwise, a value of 
SOCK_ET_ERROR is returned, and a specific error code may be retrieved by calling 
VVSAGetLastEnrorQ. 
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Error Codes WSANOTTNITIALISED 
WS AENETDO WN 
WSAEACCES 
WSAEINTR 
WSAEENPROGRESS 
WSAEFAULT 

WSAENETRESET 

WSAENOBUFS 

WSAENOTCONN 

WSAENOTSOCK 
WSAEOPSOTSUPP 

WSAESHUTDOWN 
W S AEWOULD BLOCK 
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A successful WSASiartupO must occur before 
using this API. 

The Windows Sockets an piemen tad on has detected 
that the network subsystem has failed. 

The requested address is a broadcast address, but the 
appropriate flag was not set 

The (blocking) call was canceled via 
WSACancelBiockingCaUO- 

A blocking Windows Sockets operation is in 
progress. 

The buf at to parameters are not pan of the user 
address space, or the to argument is too small (less 
than the sizeof a struct sockaddr). 

The connection must be reset because the Windows 
Sockets implementation dropped it. 

The Windows Sockets implementation reports a 
buffer deadlock. 

The socket is not connected (SOCK .STREAM 

only). 

The descriptor is not a socket. 

MSG_OOB was specified, but the socket is not of 
type SOCK _ STREAM. 

The socket has been shutdown: it is not possible to 
sendtoO on a socket after shutdown!) has been 
invoked with how set to 1 or 2. 

The socket is marked as non-blocking and the 
requested operation would block. 
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15 



20 



25 



WSAEMSGSIZE 

WS AECO NN .ABORTED 

WSAECON*NR£SET 
WSAEADDRNOTAVAIL 

WSAEAFNOSUPPORT 

WSAJEDESTADDRREQ 
WSAEiNETUNREACH 



The socket is of type SOCK_DGRAM. and the 
datagram is larger than the maximum supported by 
the Windows Sockets implementation. 

The virtual circuit was aborted due to timeout or 
other failure. 

The virtual circuit was reset by the remote side. 

The specified address is not available from the local 
machine. 

Addresses in the specified family cannot be used 
with this socket. 

A destination address is required. 

The network can't be reached from this host at this 
time. 



See AJso 



recvQ. recvfromO. socketQ. sendQ. WSAStartupO- 
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4.1.21 setsockopt() 
Description Set a sockst option. 

^include <winsock.b> 

in t PASCAL FAR setsockopt ( SOCKET s. int level, int optname. 
const char FAR * optvai. int optlen ); 



s A descriptor identifying a socket. 

level The level at which the option is defined; the only supported leveis are 

SOL.SOCKET and IPP ROTO. TCP. 

optname The socket option for which ihe value is to be set. 

opt\al A pointer to the buffer in which the value for the requested opuon is 

supplied. 

optlen The size of the oprvat buffer. 



Remarks setsockoptO sets the current value for a socket option associated with a socket of any 

type, in any suite. Although options may exist at multiple protocol levels, this 
specification only defines options that exist at the uppermost "socket" level. Options 
affect socket operations, such as whether expedited data is received in the normal data 
stream, whether broadcast messages may be sent on the socket, etc. 

There are two types of socket options: Boolean options that enable or disable a feature 
or behavior, and options which require an integer value or structure. To enable a 
Boolean option, cptval points to a nonzero integer. To disable the option optvai points 
to an integer equal to zero, opilen should be equal to sizeof(uit) for Boolean options. 
For other options, optval points to the an integer or structure mat contains the desired 
value for the option, and optlen is the length of the integer or structure. 

SO_LINGER controls the action taken when unseat data is queued on a socket and a 
closesocketO is performed. See closesocketO for a description of the way in which the 
SO.LLNGER settings affect the semantics of closesocketO. The application sets the 
desired behavior by creating a struct linger (pointed to by the optval argument) with the 
foU owing elements: 

struct linger ( . 

in: l_ono£f; 
ir.c l_linger; 

I 

To enable SO.LLNGER. the application should set t _onoff to a non-zero value, set 
ijtnger to 0 or the desired timeout (in seconds), and call setsockoptO To enable 
SO.DONTUNGER (i.e. disable SO, LINGER) l onoff should be set to zero and 
setsockoptO should be called. 

By default, a socket may not be bound (see blndO) to a-local address which is already 
in use. On occasions, however, a may be desirable to ."re-use" an address in this way. 
Since every connection is uniquely identified by the combination of local and remote 
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addresses, ihere is no problem with having two sockets bound to the same local address 
as long as the remote addresses are different. To inform the Windows Sockets 
implementation that a bindQ on a socket should not be disallowed because the desired 
address is already in use by another socket, the application should set the 
SO.REUSEADDR socket option for the socket before issuing the bin dO- Note that the 
option is interpreted only at the time of the bind(): it is therefore unnecessary (but 
harmless) to set the option on a socket which is not to be bound to an existing address, 
and setting or resetting the option after the bindi) has no effect on this or any other 
socket. 
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An application may request that the Windows Sockets implementation enable the use of 
"keep* alive" packets on TCP connections by turning on the SO_KEEP ALIVE socket 
op a on. A Windows Sockets implementation need not support the use of keep-alives: if 
it does, the precise semantics are implementation- specific but should conform to section 
4.2 3 6 of RFC 1 122: Requirements for Internet Hosts Communication Layers, If a 
connection is dropped as the result of "keep-alives" the error code WS AENETRESET is 
returned to any calls in progress on the socket, and any subsequent calls will fail with 
WSAENOTCONN. 



25 
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The TCP_NODELAY option disables the Nagie algorithm. The Nagle algorithm is 
used to reduce the number of small packets sent by a host by buffering unacknowledged 
send data until a full- size packet can be sent. However, for some applications this 
algorithm can impede performance, and TCP_ NO DELAY may be used to turn it off. 
Application writers should not set TQP_NODELAY unless the impact of doing so is 
well -understood and desired, since setting TCP.NODELAY can have a significant 
negative impact of network performance. TCP.NODELAY is the only supported 
socket option which uses level IPPROTO_TCP: ail other options use level 
SOL.SOCKET. 



35 



Windows Sockets suppliers are encouraged (but not required) to supply output debug 
information if the SO_DEBUG option is set by an application. The mechanism for 
generating the debug information and the form it takes are beyond the scope of this 
specification. 

The following options are supported far selsockoptO- The Type identifies the type of 
data addressed by oprval. 
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SO 



Value 

SO.BROADCAST 

SO.DEBUG 
SO_DONTLINGER 



SO.DONTROLTE 
SO JCEEP ALIVE 
SO.LCs'GER 

SO_OOB INLINE 

SO.RCVBUF 
SO.REUSEADDR 



Type 
BOOL 

BOOL 
BOOL 



BOOL 
BOOL 
struct Linger 
FAR • 
BOOL 

int 

BOOL 



Mrnning 

Allow transmission of broadcast messages on the 
socket. 

Record debugging information. 

Don't block close waiting for unsent data to be 

sent. Setting this option is equivalent to setting 

SO .LINGER with lj>noff set to zero. 

Don't route: send directly to interface. 

Send keepaiives 

Linger on close if unsent data is present 

Receive out -of- band data in the normal data 
stream. 

Specify buffer size for receives 

Allow the socket to be bound to an address which 

is already in use. (See bindQ.) 
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SO.SNDBLT int Specify buffer size for sends. 

TCP_NODELA Y BOOL Disables the Nagle algorithm for send coalescing. 

BSD options aot supported for selsockoptO axe; 



Value 


Type 


Vfe.inina 


SO.ACCLrMCONN 


BOOL 


Socket is lis le ning 


SO.ERROR 


int 


Get error status and clear 


SO.RCVLOWAT 


int 


Receive low water mark 


SO.RCVTIMEO 


int 


Receive timeout 


SO.SNDLOWAT 


int 


Send low water mark 


SO.SNT)TTMEO 


int 


Send timeout 


SOJTYPE 


int 


Type of the socket 


IP^OPTIONS 




Set options field in IP header. 



Return Value If qo error occurs. setsockoptO returns 0. Otherwise, a value of SOGGET_ERROR is 
returned, and a specific error code may be retrieved by calling WSAGetLastErrorO- 



Error Codes WSANOTTNTITALISED 



WSAENETDOWN 
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WSAEFAULT 



WS AEINFROGRESS 



WSAEINVAL 



35 



WSAENETRESET 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the oetwork subsystem has failed. 

oprvai is not in a valid pan of the process address 
space. 

A blocking Windows Sockets operation is in 
progress. 

Uvel is aot valid, or the information in optval is not 
valid. 



Connection has timed out when SO.KEEP ALIVE is 
set. 



WSAENOPROTOOPT The option is unknown or unsupported. In 

particular. SO_BROADCAST is not supported on 
sockets of type SOCK_ STREAM, while 
SO.DONTLINGER, SO.KEEP ALIVE, 
SO.UNGER and SO_OOB INLINE are not 
supported on sockets of type SOCK_DGRAM. 



WSAENOTCONN 



Connection has been reset when SO.KEEP ALIVE 
is set 



so 



WSAENOTSOCK 



The descriptor is aot a socket. 



See Also 



bindO. getsockoptO. ioctisocketQ. socketO. WSAAsyocSelectQ- 
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4.1.22 shutdown() 

Description Disable sends and/or receives on a socket, 
^include <winsocW.h> 



int PASCAL FAR shutdown ( SOCKET s % int how ); 

10 



s A descriptor identifying a socket. 

how A flag that describes what types of operation will no longer be 

75 allowed. 



Remarks shutdownO is used on ail types of sockets to disable reception, transmission, or both. 

If how is 0. subsequent receives on the socket will be disallowed. This has no effect on 
20 the iower protocol layers. For TCP. the TCP window is not changed and incoming data 

will be accepted (but not acknowledged) until the window is exhausted. For UDP. 
incoming datagrams are accepted and queued. In ao case will an ICMP error packet be 
generated. 

25 If how is I . subsequent sends are disallowed. For TCP sockets, a FIN will be sent. 

Setting how to 2 disables both sends and receives as described above. 

Note that shutdownO does not close the socket, and resources attached to the socket 
30 will not be freed until closesocketQ is invoked. 
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Comments shutdownO does not block regardless of the SO_LINGER setting on the socket. 

An application should oot rely on being able to re-use a socket after it has been shut 
down. In particular, a Windows Sockets implementation is not required to support the 
use of con nee t0 on such a socket 

Return Value If no error occurs. shutdownO returns 0. Otherwise, a value of SOCKET, ERROR is 
returned, and a specific error code may be retrieved by calling WSAGetLastErrorQ. 



Error Codes WSANOTTNTTIALISED 

WSAENETDOWN 

WSAETNVAL 
WSAETNFROGRJESS 
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A successful WSAStartupO must occur before 
using thw API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

how is not valid. 

A bloc long Windows Sockets operation is in 
progress. 



WSAENOTCONN 
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WSAENOTSOCK 



The socket is not connected (SOOK_5TRJEAM 
only). 



The descriptor is not a socket. 
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5 

See Also connect(). soeketQ. 
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5 4.1.23 socket() 

Description Create a socket. 

^include <winsnck.b> 

10 SOCKET PASCAL FAR socket ( int a/, int type, int protocol ): 



af An address format specification. The only format currently supported 

is PF_ENET. whjcn is the ARP.A laternet address formal. . 



is 



20 



2S 



30 



type A type specification for the new socket. 

protccoi A particular protocol to be used with the socket, or 0 if the caller does 

not wish to specify a protocol. 

Remarks socketO allocates a socket descriptor of the specified address family, data type and 

protocol, as well as related resources. If a protocol is not specified (Le. equal to 0). the 
default for the specified connection mode is used. 

Only a single protocol exists to support a particular socket type using a given address 
format. However, the address family may be given as AF_UNSPEC (unspecified), in 
which case the protocol parameter must be specified. The protocol number to use is 
particular to the "communication domain" in which communication is to place. 

The following rype specifications are supported: 



Tvpe Explanation 

S OCK _ STREAM Provides sequenced, reliable, two-way, connection- 

based byte screams with an out-of*band data 

35 

transmission mechanism. Uses TCP for the Internet 
address family. 

SOCK_DGRAM Supports datagrams, which axe connectionless, 

unreliable buffers of a fixed (typically small) 
40 maximum length. Uses UDP for the Internet address 

family. 



Sockets of type SOCK _ STREAM are full-duplex byte streams. A stream socket must 
be in a connected state before any data may be sent or received on it A connection to 
another socket is created with a connectO call. Once connected, data may be 
transferred using seodO and recvO calls. When a session has been completed, a 
closesocketO must be performed. Out -of- band data may also be transmitted as 
described in seodO and received as described in recvO- 

The communications protocols used to implement a SOCK_STRJEAM ensure mat data 
is not lost or duplicated. If data for which the peer protocol has buffer space cannot be 
successfully transmiced within a reasonable length of time, the connection is 
considered broken and subsequent calls will fail with the error code set to 
WSAETTMEDOUT. 
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SOCK _D GRAM sockets allow sending and receiving of datagrams to and from 
arbitrary peers using sendto() and recvfroraO- If such a socket is conuect()ed to a 
specific peer: datagrams may be send to that peer sendO and may be received from 
(only) this peer using recvf). 



Return Value If no error occurs, socketf) returns a descriptor referencing the new socket. Otherwise. 

a value of ENVAJL ED _ SOCKET is rerurned. and a specific error code may be retrieved 
by calling YVSACetLastErrorCK 



Error Codes W S ANOTTNTTIAL IS ED 
WSAENFTDOWN 

WSAEAFNOSLTPORT 
WSAEENTROGRESS 

WSAEMFILE 
WSAENOBUFS 

WSAEFR0T0N0SLTPORT 
W S AEPROTOTYPE 

WSAESOCKTNOSUPPORT 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implement-anon has detected 
that the network subsystem has failed. 

The specified address family is not supported. 

A blocking Windows Sockets operation is in 
progress. 

No more file descriptors are available. 

No buffer space is available. The socket cannot be 
created. 

The specified protocol is not supported. 

The specified protocol is the wrong type for this 
socket. 

The specified socket type is not supported in this 
address family. 
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See Also acceptO. bindO. coonectO. getsockoameO. getsockoptO. setsockoptO. listenO. recvO. 
recvfromO. select Q. sendQ. seadtoQ. shutdowaQ. ioctlsocketQ. 
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4.2 Database Routines 
4.2.1 gethostbyaddr() 

Description Get host information cores ponding to an address. 
£ include <winsock.h> 

struct hostent FAR * PASCAL FAR gethostbyaddr ( const char FAR ■ addr. int 
len, int type ); 



75 addr A pointer to an address in network byte order. 

ten The length of the address, which must be 4 for PF_FNET addresses. 

rype The type of the address, which must be PF INET 

20 

Remarks gethostbyaddrO re rums a pointer to the following structure which contains the name(s) 

and address which correspond to the given address. 

struct hostent ( 
25 char FAR * h_name; 

char FAR * FAR * h_alxases; 
short h^addr type- 
short h_length; 

char FAR ♦ FAR * h addr list; 
) ; - - 

30* 

The members of this structure are: 
Element Llsagfi 

h.oame Official name of the host (PC). 

h_aliases A NULL-terminfltmd array of ai tern ate names. 

35 h.addrrype The type of address being returned; for Windows Sockets this is 

always PF.INET. 

h .length The length, in bytes, of each address: for FF JNET. this is always 4. 

h_addr_list A NLXL-terminated list of addresses for the host. Addresses are 
returned in network byte order. 



40 



The macro h.addr is defined to be h_addr_list[0] for compatibility with older software. 



The pointer which is returned points to a structure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
45 to free any of its components. Furthermore, only one copy of this structure is allocated 

per thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 

so Return Value If no error occurs, gethostbyaddr 0 returns a pointer to the hostent structure described 

above. Otherwise it re rums a NULL pointer and a specific error number may be 
retrieved by calling WSAGetLastErrorO. 

Error Codes WS ANCnTNTTTALISED A successful WSASurtupO must occur before 

55 using this API. 
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WSAENETDOWN 

WSAHOST_NOT_FOUND 
WSATRY_ AGAIN 

WSANO.RECOVERY 

WSANO.DATA 
WSAEESTROGRESS 

WSAEINTR 



The Windows Sockets implementation has detected 
chat die network subsystem has failed. 

Authoritative .Answer Host Dot found. 

Non- Authoritative Host not found, or 
SERVER-FAIL. 

Non recoverable errors. FORMERR. REFUSED. 

notimp. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACancelBlockingCalJO. 



SeeAJso 



WSAAsyncGetHostByAddrQ. gethostbynaxneO. 
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4.2.2 gethostbyname() 

DescrlptJ n G^i host inform a uoq corresponding :o a hostname, 
"include <wiosock.h> 

struct hostent FAR • PASCAL FAR gethostbynarne ( const char FAR • name ); 



15 



20 



25 



name A pointer to the name of the host. 

Remarks gethostbynameO returns a pointer to a hostent structure a_s described under 

getbostbyaddrO. The contents of this strucnire correspond to the hostname name. 

The pointer which is re aimed points to a structure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify ibis structure or 
to free any of its components. Furthermore, only one copy of this structure is allocated 
per thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 

A gethostbynameO implementation must not resolve IP address strings passed to it. 
Such a request should be created exactly as if an unknown host name were passed. An 
applicadon with an IP address string to resolve should use inet.addrO to convert the 
suing to an IP address, then getbostbyaddrO to obtain the hostent structure. 
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Return Value If no error occurs. gethostbynameO returns a pointer to die hostent structure described 
above. Otherwise it returns a NULL pointer and a specific error number may be 
retrieved by calling WSAGetLastErrorO. 



Error Codes WSANOTTNTTIALISED 



WSAENFTDOWN 



WSAHOST.NOT.FOUND 
WSATRY_ AGAIN 

WSANCLRECOVERY 

WS ANO_ D AT A 
WSAONFROCRESS 

WSAEINTR 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Authoritative .Answer Host not found. 

Non-Authoritative Host not found, or 
SERVERFATL. 

Non recoverable errors. FORMERR. REFUSED. 
NOTTMP. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACaucelBlockingCallO. 



See Also 
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VVSAAsyncGrtJIostByNameO. getbostbyaddrO 
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4.2.3 gethostname() 

Description Re rum the s Land aid host name for the local machine, 
^include <winsock.b> 

i nt PASCAL FAR getbostname ( char FAR • name, iut nameien ); 
name A pointer to a buffer that will receive the host name. 

nameien The length of the buffer. 



Remarks 



Return Value 



Error Codes 



See AJso 



This routine returns the name of the local host into the buffer specified by the name 
parameter. The host name is returned as a null- terminated string. The form of the host 
name is dependent on the Windows Sockets implementation- -it may be a simple host 
name, or it may be a fully qualified domain name. However, it is guaranteed that the 
name returned will be successfully parsed by getbostbynameO and 
WSAAsyocGetHostBvNameO. 

If no error occurs. gethostnameO returns 0. otherwise it returns SOCKET_ERROR and 
a specific error code may be retrieved by calling WSACetLastErrorO. 



WSAEFAULT 
WSANOTTNTTTALISED 

WS AENETDO WN 

WSAEINPROGRESS 



The nameien parameter is too small 

A successful WSAStarrupO must occur before 
ncing rhi* API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 



getbostbynameO, VVSAAsyncGetHostByNameO- 
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5 4.2.4 getprotobynameO 

Description Get protocol information corresponding to a protocol name, 
^include <winsock.b> 

w I struct protoent FAR • PASCAL FAR getprotobyname ( const cbar FAR • name ); 

name A pointer to a protocol name. 

15 Remarks getprotobynameO re rums a pointer to the following structure which contains the 

name(s) and protocol number which correspoad to the given protocol name. 

srrurrr. protoent { 

char FAR p_name; 
char FAR * FAR * p_a liases; 
short p^proco; 

t ; 

The members of this strucrure arc: 
Element Usage 

25 p.name Official name of the protocol. 

p_aiiases A NULL- term i n a rrd array of alternate names. 

P_proto The protocol number, in host byte order. 

The pointer which is returned points to a structure which is allocated by the Windows 
30 Sockets library. The application must never attempt to modify this structure or to free 

any of its compooents. Furthermore only one copy of rhU structure is allocated per 
thread, and so the application should copy any uxformation which it needs before 
issuing any other Windows Sockets API calls. 
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40 
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Return Value If no error occurs. getprotobynameO returns a pointer to the protocol structure 

described above. Otherwise it returns a NULL pointer and a specific error number may 
be retrieved by railing WSAGetLastErrorO. 



Error Codes 



WSANOTINTnALlSED 

WSAENETDOWN 

WS ANO.RECO VERY 

WSANO.DATA 
WSAHNPROGRESS 

WSAEINTR 



A successful WSAStartupO must occur before 

»ging th\< APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Nod. recoverable errors. FORMERR, REFUSED. 
N0T1MP. 

Valid name. no. data record of requested type. 

A bloc king Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACancelBlockingCaUO. 
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See Also WSAAsyncGetProtoByNaroeO. S*tP rf >to by nu ruber Q 
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4.2.5 getprotobynumber() 

De script l n Get protocol information corresponding to a protocol aumber. 
£ Include <winsocW.h> 

struct protoent FAR • PASCAL FAR getprotobynumber ( int number ); 



number 



A protocol number, in host byte order. 
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Remarks This function returns a pointer to a protoent s true aire as described above in 

getprotobynameO The contents of the structure correspond to the given protocol 
number. 

The pointer which is returned points to a structure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
to free any of its components. Furthermore, only one copy of this structure is allocated 
per thread, and so the application should copy any inform acion which it needs before 
issuing any other Windows Sockets API calls. 

Return Value If no error occurs. getprotobynumberO returns a pointer to the protoent structure 

described above. Otherwise it returns a NULL pointer and a specific error number may 
be retrieved by calling WSAGetLastErrorO. 



Error Codes 



WSANOTTNITLALISED 

WS AENFTDOWN 

WS ANO.RECO VER Y 

WSANO.DATA 
WSAHNPROGRESS 

WSAEINTR 



A successful WSAStartnpO must occur before 

"*ing thk API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Nou recoverable errors. FORMERR. REFUSED 
NOTTMP. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACancelBIockingCallO. 



See Also 



WSAAsyncGetProtoByNumberO. getprotobynameO 
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4.2.6 getservbyname() 

Description Get service information corresponding to a service name and protocol, 
^include ovinsock.h^ 

struct serveol FAR • PASCAL FAR getservbynunie ( const char FAR * name, 
const char FAR * prow ); 



name A pointer to a service name. 

| protn An optional pointer to a protocol name. If this is NULL. 

getservbyoameO returns the first service entry for which the name 
matches the $_oame or one of the s_aliases. Otherwise 
getservbynameO matches both the name and the pro to. 

Remarks getservbynameO returns a pointer to the following structure which contains the 

aameis) and service number which correspond to the given service name. 



25 



icz server.: I 

char FAR * s_na.ne; 

char FAR ' FAR • s_aiiases; 

shcr: s^cort; 

char FAR* * s_pr3to; 
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The members of this structure are: 



Element 



Usage 



s_name Official name of the service. 

s_ai;ases A NTJLL-terminated array of alternate names. 

s_port The port number at which the service may be contacted. Port 

numbers are returned in network byte order. 
s_proto The name of the protocol to use when contacting the service. 

The pointer which is returned points to a structure which is allocated by the Windows 
Sockets library. The application must never attempt to modify this structure or to free 
any of its components. Furthermore only one copy of this s true cure is allocated per 
thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs. getservbynameO returns a pointer to the serve at structure described 
above. Otherwise it re rums a NULL pointer and a specific error number may be 
retrieved by calling WSAGetLasLErrorO. 



Error Codes WSANCHTNTTIALISED 
WSAENETDOWN 
WSANO.RECOVERY 



A successful WSASlartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
mat the network subsystem has failed. 

Nog recoverable errors. FORMERR, REFUSED. 
NOTTMP. 
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5 VVSANO.DAT A Valid came, qo daLa record of requested type. 

WSAEINPROGRESS A blocking Windows Sockets operation is in 

progress. 

10 WSAEENTR The (blocking) call was canceled via 

WSACaucelBlockiogCaliO. 

See AJSO WSAAsyncCetServByNameO, getservbyportO 
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4.2.7 getservbypor1() 

Description Get service Latormauon corresponding to a port and protocol, 
"include <winsock.h> 

struct servent FAR * PASCAL FAR getservbyport ( int port, const char FAR • 

proio ); 



15 
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port The port for a service, in network byte order. 

pro to An optional pointer to a protocol name. If this is NULL. 

gets* rv by port 0 returns the first service entry for which the port 
matches the s_pon. Otherwise getservbyportO matches both the port 
and the proto. 

Remarks getservbyportO returns a pointer a servent s true cure as described above for 

getservbyaameO 

The pointer which is returned points to a structure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
to free any of its components. Furthermore, only one copy of this structure is allocated 
per thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 
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Return Value If no error occurs. getservbyportO returns a pointer to the servent structure described 
above. Otherwise it returns a NULL pointer and a specific error number may be 
retrieved by railing WSAGetLastErrorQ. 



Error Codes 



WSANOTTNTTLAJLISED 

WSAENETDOWN 

WSANO_R£COVERY 

WSANO.DATA 
WSAETNPROGRESS 

WSAJEINTR 
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A successful WSAStartupO must occur before 

n<ing fhi^ API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

N*on recoverable errors. FORMERR. REFUSED, 
NOTTMP. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
YVSACanceifi lockingCallO* 



See Also 



WSAAsyocGeiServByPortO. getservbynameO 
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4.3 Microsoft Windows-specific Extensions 
4.3.1 WSAAsyncGetHostByAddrO 

Description Get host infoiraauon coirespondlag to an address - asynchronous versioa. 
"include <winsock.b> 

HANDLE PASCAL FAR WSAAsyncGetHostByAddr ( HWND hWnd. 
unsigned Lnt »**.Vfjg, const char FAR * addr x int Un. ial type, char FAR • buf, in t 
buflen ); 



hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

The message to be received when the asynchronous request 
completes. 

A pointer to the network address for the host. Host addresses are 
stored in network byte order. 

The length of the address, which must be 4 for PF.INET. 

The type of the address, which must be PF_INET. 

A pointer to the data area to receive the hostent data. Note that this 
must be larger than the size of a hostent structure. This is because the 
data area supplied is used by the Windows Sockets implementation to 
contain not only a hostent structure but any and all of the data which 
is referenced by members of the hostent structure. It is recommended 
that you supply a buffer of MAXGETHOSTSTRUCT bytes. 

The size of data area buf above. 

Remarks This function is an asynchronous version of getbostbyaddrO. and is used to retrieve 

host name and address information corresponding to a network address. The Windows 
Sockets implementation initiates the operation and returns to the caller immediately, 
passing back an asynchronous h*nH1fl which the application may use to identify the 
operation, When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The w Par am argument contains the asynchronous h»nr]]+ & 
returned by the original function call. The high 16 bits of IParam contain any error 
code. The error code may be any error as defined in winsockJi. An error code of zero 
Indicates successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call contains a hostent structure. 
To access the elements of this structure, the original buffer address should be cast to a 
hostent structure pointer and accessed as appropriate. 

Note that if the error code is WSAENOBUFS. it indicates that the sixe of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IF a ram contain the ***** of buffer required 
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to supply ALL the requisite infonratioa. If the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetHostByAddrO function call with a 
buffer large enough to receive ail the desired inform ad on. (i.e. no smaller than the low 
i 6 bits of IParam). 
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The error code and buffer length should be extracted from the IParam using the macros 
WSAGETAS YNCERROR and WSAGETAS YNCBUFLEN. defined in winsock.h as: 



4def ine WSAGETA 5 TN C Z R?.C ?. ( l?ar<an) 
4def in 9 W S AC E TA S YN C BUT LZ N ( 1 Pa ram) 



HIWORD ( i?ira.7.) 
L O WO ?JD ( iPd r cl-h ) 



The use of these macros will maximize the portability of the source code for the 
application. 

Return Value The return value specifies whether or not the asynchronous operation was success fuJIv 
initiated. Note that it does qqi imply success or failure of the operation itself. 

If the operation was successfully initiated, VVSAAsyncGetHostByAddrO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACancelAsyocRequestO* It can also be used to match up asynchronous operations 
and completion messages, by examining the * Par am message argument. 

If the asynchronous operation could not be initiated. WSAAsyncCetHostByAddrO 
returns a zero value, and a specific error number may be retrieved bv calling 
WSAGetLastEnrorO- 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a bos tent structure together with the contents of data areas referenced by 
members of the same hostent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in winsockJi). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation must re- post that message as long as the window 
exists. 



45 



Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the IParam in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

As described above, they may be extracted from the IParam in the reply message using 
the WSAGETAS YNCERROR macro. 
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WSAENETDOWN 

WSAENOBUFS 
WSAHOST.NOT.FOUNU 



The Windows Sockets implementation has detected 
that the nerwork subsystem has failed. 

No/insufficient buffer space is available 

Authoritative Answer Host not found. 
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WSATRY.AGAIN 
WSANO.RECOVERY 
W S ANO_ DATA 



Noo- Authoritative Host not found, or 
SERVERFATL. 

Nod recoverable errors. FORMERR REFUSED 

nottmp. 

Valid name, no data record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WSANOTTNTTLALISED 
WSAENETDOWN 
WSAHNPROGRESS 
WS AEWOULDBLOCK 



A successful WSAStarrupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this rime due to resource or other constraints wi thin 
the Windows Sockets implementation. 



See AJso 



gethostbyaddrQ. WSACancelAsyocRequestO 
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4.3.2 WSAAsyncGetHostByName() 

Description Get host infonnadoa corresponding to a hostname - asynchronous version, 
^include <winN>clt.h> 

HANDLE PASCAL FAR WSAAsvocGetHostByName ( HYVND hWnd, 
unsigned int w\fsg. const char FAR • name, char FAR * buf. int buflen.): 

hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

*'Msg The message to be received when the asynchronous request 

completes. 

name A pointer to the oame of the host. 

buf A pointer to the data area to receive the hostent data. Note that this 

must be larger than the size of a hostent structure. This is because the 
data area supplied is used by the Windows Sockets implementation to 
contain not only a hostent structure but any and all of the data which 
is referenced by members of the hostent structure. It is recommended 
that you supply a buffer of MAXGETHOSTSTRUCT bytes. 

buflen The size of data area buf above; 

Remarks This function is an asynchronous version of gethastbyaameO. and is used to retrieve 

host name and address information corresponding to a hostname. The Windows 
Sockets implementation initiates the operation and re turns to the caller immediately, 
passing back an asynchronous r^lr hanrfl* which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application s window hWnd receives 
message *>\fsg. The wParam argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of IParam contain any error 
code. The error code may be any error as defined in winsockJi. An error code of zero 
indicates successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call rantjui^ a hostent structure. 
To access the elements of mis structure, the original buffer address should be cast to a 
hostent structure pointer and accessed as appropriate. 

Note that if the error code is WSAENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IParam contain the of buffer required 
to supply ALL the requisite information. if the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetHostByNameO function call with a 
buffer large enough to receive all the desired informadon (i.e. no smaller than the low 
16 bits of IParam). 

The error code and buffer length should be extracted from the LP a ram using the macros 
WSAGETASVNCERROR and W S AGETAS YNCB IfFT FN . defined in winsock.h as: 
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*~e; :r.e w 3 A C- " A 5 'fN C 1 ?J5 O ?. (i?arin) 
^s:::e W S A G E 7 A 5 fN C 3 ITr LIN ( ram) 



HI WORD ( l?d:i.T,) 
1CWCRD (l?«ara.Ti) 
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Return Value 



Comments 



The use of these macros will maximize the portability of the source code for the 
application. 



The return value specifies whether or not the asynchronous operation was 'successfully 
initiated. Note that it does net imply success or failure of the operation itself. 

If the operation was successfully initiated. WSAAsyocGetHostByNameO rerums a 
aonzsro value of type HANDLE which is the asynchronous task handle for the request. 
Tais value can be used in two ways. It can be used to cancel the operation using 
WSACancetAsyocRequestO- It can also be used to match up asynchronous operations 
and completion messages, by examining the ^ Par am message argument. 

£f the asynchronous operation could not be initiated. WSAAsyncGetHostByNameQ 
returns a zero value, and a specific error number may be retrieved by calling 
WSAGetl.ast£rTorO. 

The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a has tent structure together with the contents at data areas referenced by 
members of the same hostent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in winsockJi). 



Notes For 
Windows Sockets 



Suppliers 



Error Codes 



It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation musj re-post that message as long as (he window 
exists. 

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the LP a ram in the message. 

The following error codes may be set when an application window receives a message. 
As described above, they may be extracted from the IP or am in the reply message usina 
the WSAGETASYNCERROR macro 



so 
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WSAENETDOWN 

WSAENOBUFS 

WSAHOST_NOT_FOUND 

WSATRY.AGAjQN 

WSANO.RECOVERY 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

No/insufficient buffer space is available 

Authoritative .Answer Host not found. 

Non- Authoritative Host not found, or 
SERVERFAJL. 

Non recoverable errors. FORMERR, REFUSED 
NOTIMP. 
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WSANO.DATA 



w 
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20 



Valid name, no data record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WS AN0TTNTT1ALISED 
WSAENETDOWN 
WSAEINFROGRESS 
WSAEWOLTLDBLOCK 



A successful VVSAStarrupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the oecwork subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
mis rime due to resource or other constraints within 
the Windows Sockets implementation. 



See AJso 



gethostbyoameO. WSACancelAsyncRequestO 
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4.3.3 WSAA yncGetProtoByName() 

Description Get protocol information corresponding to a protocol name - asynchronous version, 
^include <winsock.b> 

HANDLE PASCAL FAR WSAAsyncGetProtoByName ( H WND hWnd % 
unsigned int -.f.Vj ? , const char FAR • name, char FAR * buf int buflen[)x 



hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

wMsg The message to be received when the asynchronous request 

completes. 

name A pointer u> the protocol name to be resolved. 

bu f A pointer to the data area to receive the protoem data. Note that this 

must be larger than the size of a proioent s true cure. This is because 
the data area supplied is used by the Windows Sockets 
implementation to contain not only a protoeat structure but any and 
2S all of the data which is referenced by members of the protoent 

structure. It is recommended that you supply a buffer of 
MAXGFTHOSTSTRUCT bytes. 



15 



20 



buficn The size of data area buf above. 



30 



Remarks This function is an asynchronous version of getprotobynameO. and is used to retrieve 

the protocol name and number corresponding to a protocol name. The Windows 
Sockets implementation initiates the operation and returns to the caller immediately, 
passing back an aSYachfgpoui task handle which the application may use to identify the 
3S operation. When the operation is completed, the results (if any) are copied into the 

buffer provided by the caller and a message is sent to the applications window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The w Par am argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of IP as am contain any error 
code. The error code may be any error as defined in winsockJr An error code of zero 
indicates successful completion of the asynchronous operation On successful 
com pie don. the buffer supplied to the original function call contains a protoem 
structure. To access the elements of this s true cure, the original buffer address should be 
cast to a protoent structure pointer and Kxessed as appropriate. 



40 



45 



Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer 
specified by buficn in the original call was too small to contain all the resultant 
inform a Don. In this case, the low 16 bits of IP as am contain the size of buffer required 
to supply ALL the requisite information. If the application decides that the partial da;a 
50 is inadequate, it may reissue the WSAAsyocGetProtoByNameO function call with a 

buffer large enough to receive all the desired information (i.e. no smaller than the low 
16 bits of IParam). 

The error code and buffer length should be extracted from the IParam using the macros 
55 WS AGET AS YSCERRO R and WSAGETASYNCBUFLEN. defined in winsock.h as: 



BNSOOCID: <EP 07709S8A1 I > 



90 



EP 0 770 958 A1 



WSAAsyncGetPr t ByName 77 



10 



4ce fire WSAGETASYNCrl-.TLIN' ( l?d: d_T. ) 



The use of these macros will mxximize the portability of the source code for the 
application 
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Return Value The return value speciiies whether or not the asynchronous operatioa was successfully 
initiated. Note that it does OCI imply success or failure of the operation itself. 

If the operatioa was successfully initiated. WSAAsyncGetProtoByNameO returns a 
nonzero value of rype HANDLE which is the asynchronous task handle for the request. 
This value can be used in rwo ways. It can be used to cancel the operation using 
WSACancelAsyocRequestO* It can also be used to match up asynchronous operations 
and completion messages, by examining the wParam message argument. 

If the asynchronous operatioa could not be initiated. WSAAsyncGetProtoByNameO 
returns a zero value, and a specific error number may be retrieved by calling 
WSAGetLast£rrorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a protoent structure together with the contents of data areas referenced by 
members of the same protoent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in wtnsockJi). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation must re-post that message as long as the window 
exists. 

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the I Par am in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

As described above, they may be extracted from the LP or am in the reply message using 
the WSAGETASYNCERROR macro. 
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WSAENETDOWN 

WSAENOBUFS 
WSAHOST.NOT.FOUND 
WSATRY_ AGAIN 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

No/insufficient buffer space is available 

Authoritative Answer Host not found. 

Non- Authoritative Host not found, or 
SERVERFAJL. 



ss 



WSANO.RECOVERY 



Nou recoverable errors. FORMERR. REFUSED. 
NOTTMP. 
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WSANO_DATA Valid name, no data record of requested type. 

The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 

W S ANOTTNTT1AL IS ED A successful WSAStartupO must occur before 

using this API. 

WSAENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

WSAHNPROGRESS A blocking Windows Sockets operation is in 

progress. 

WS AEWOULDBLOGK The asynchronous operation cannot be scheduled at 

this time due to resource or other constraints within 
the Windows Sockets implementation. 

See Also getprotobyoameO. WSACancelAsyncRequestO 
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4.3.4 WSAAsyncGetProtoByNumber() 

Description Get protocol information corresponding to a protocol number - asyuchr nous version, 
^include <wiusock.h> 

HANDLE PASCAL FAR WS A AsyocGe tProtoByNumber ( HWND hWnd, 
unsigned int wMsg 9 int number, char FAR * buf int buflen ); 



15 



20 



hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

"Msg The message to be received when the asynchronous request 

completes. 

number The protocol number to be resolved, in host byte order. 

buf A pointer to the data area to receive the protoent data. Note that this 

must be larger than the size of a protoent structure. This is because 
the data area supplied is used by the Windows Sockets 
implementation to contain not only a protoent structure but any and 
ail of the data which is referenced by members of die protoent 
structure. It is recommended that you supply a buffer of 
MAXGETHOSTSTRUCT bytes. 



buflen The size of data area buf above. 

Remarks This funcdan is an asynchronous version of getprotobyuumberO. and is used to 
retrieve the protocol name and number corresponding to a protocol number. The 
Windows Sockets implementation initiates the operation and returns to the caller 
immediately, passing back an mivnehrem™* t**k h«nHU which the application may use 
to identify the operation. When the operation is completed, the results (if any) are 
copied into the buffer provided by the caller and a message is sent to the application's 
window. 



When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The wParam argument ««t»int (he asynchronous h»nHU as 
returned by the original function call. The high 16 bits of IP or am contain any error 
code. The error code may be any error as defined tnwinsockJi. An error code of zero 
in d icat es successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call r^n/iin^ a protoent 
structure. To access the elements of this structure, the original buffer address should be 
cast to a protoent structure pointer and accessed as appropriate. 

Note that if the error code is WSAJENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IP or am contain the size of buffer required 
to supply ALL the requisite information. If the application decides that the partial data 
is i nadequate, it may reissue the WSAAsyncGetProtoByNumberO function call with a 
buffer large enough to receive all the desired information (Le. no smaller than ±c low 
16 bits of IParam). 



'NSOOCID: <EP 0770958A1 \ > 



93 



EP 0 770 958 A1 



WSAAsyncGetProtoByNumber 80 



10 



The error code and buffer length should be extracted from the i Par am using the macros 
WS AGETAS YNCERROR and WSAGETASYNCBUFLEN. defined in winsock.n as; 

Jdefine WSAGETASWCERRCRC IParam) HI WORD UParam) 

.♦define WSAGETASYNCBUFLEN (lParan) LOWORD (IParam) 

The use of these macros will maximize the portability of the source code for the 
application. 
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Return Value The return value specifies whether or not the asynchronous operation was successfully 
initiated. Note that it does am imply success or failure of the operation itself. 

If the operation was successfully initiated. WSAAsyncGetProtoByNumberO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request 
This value can be used in two ways. It can be used to cancel the operation using 
WSACancelAsyncRequestO. It can also be used to match up asynchronous operations 
and completion messages, by examining the w Par am message argument. 

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumberO 
returns a zero value, and a specific error number may be retrieved by callina 
WSAGetLastErrorO. 



Comments 



The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a protoent structure together with the contents of data areas referenced by 
members of the same protoent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in wiosockii). 



Notes For 
Windows Sockets 



Suppliers 



Error Codes 



It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation msi re-post that message as long as the window 
exists. 

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the IParam in the message. 

The following error codes may be set when an application window receives a message 
As described above, they may be extracted from the IParam in the reply message usina 
the WSAGETASXNCERROR macro. message using 
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WSAENETDOWN 

WSAENOBUFS 

WSAHOST_NOT_FOUND 

WSATRY.AGAIN 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

No/insufficient buffer space is available 

Authoritative Answer Host not found. 

Non* Authoritative Host not found, or 
SERVERFAIL. 
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WSANCLRECOVERY 



Non recoverable errors. FORMERR. REFUSED. 
NOTTMP. 



WSANO.DATA 



Valid name, oo data record of requested type. 
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The following errors may occur at the rime of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WS ANOTTN1T1ALISED 



WSAENETDOWN 



WSAEINPROGRESS 



WSAEWOULDBLOCK 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 



See Also 



The asynchronous operation cannot be scheduled at 
this time due to resource or other constraints wi thin 
the Windows Sockets implementation. 
getprotobyoumberO. WSACanceiAsyncRequestO 
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4.3.5 WSAAayncGetServByNameO 

Description Get service information c ones ponding to a service name and port - asynchronous 
version. 

#ioclude <wiosock.b> 

HANDLE PASCAL FAR WSAAsyocCetServByName ( HWND hWnd, 
unsigned int wMsg, const char FAR * name, const char FAR * proio, char FAR * 
bu/ 9 tot buflen ); 



15 HWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

*>Msg The message to be received when the asynchronous request 

completes. 



20 



name A pointer to a service name. 

proto A pointer to a protocol name. This may be NTJT-L. in which case 

WSAAsyncGetServByNameO will search for the first service entry 
25 for which sjuvne or one of the s aliases matches the given name. 

Otherwise WSAAsyncGetServByNameO matches both name and 

proto. 

buf A pointer to the data area to receive the serveni data. Note that this 

30 must be larger than the size of a servent structure. This is because the 

data area supplied is used by the Windows Sockets implementation to 
contain not only a servent structure but any and all of the data which 
is referenced by members of the servent structure. It is recommended 
that you supply a buffer of MAXGETHOSTSTRUCT bytes. 
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buflen The size of data area buf above. 

Remarks This function is an asynchronous version of getservbynameO. and is used to retrieve 
service information corresponding to a service name. Tne Windows Sockets 
imp lr men c ati on initiates the operation and returns to the caller immediately, passing 
back an i<vnrhmnmit ndr h«nHU which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The w Par am argument ™m« the asynchronous t***r h« ^| r u 
returned by the original function call. The high 16 bits of IP or am contain any error 
code. The error code may be any error as defined in wiosockJi. An error code of zero 
indicates successful completion of the asynchronous opera don. On successful 
completion, the buffer supplied to the original function call contains a hostent structure. 
To a cces s the elements of this structure, the original buffer address should be cast to a 
hostent structure pointer and accessed as appropriate. 

Note that if the error code is WSAENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of LParam contain the size of buffer required 
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to supply ALL the requisite information. If the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetServByNameO function call with a 
buffer large enough to receive all the desired information (i.e. a smaller 'haq the low 
16 bits of IParam). 



The error code and buffer length should be extracted from the IParam using the macros 
WSAGETAS YNCERROR and WSAGETASYNCBUFLEN. defined in wiasock.h as: 

Jtdefine WSAGETAS YNCERROR ( IParam) HIWORD ( IParam) 

#define WS AGE TASYNCBUTLEN (IParam) LOWORD (IParam) 

The use of these macros will maximize the portability of the source code for the 
application. 



Return Value The return value specifies whether or not the asynchronous operation was successfully 
initiated. Note that it does not imply success or failure of the operation itself. 

If the operation was successfully initiated. WSAAsyncGetServByNameO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACancelAsyncRequestO. It can also be used to match up asynchronous operations 
and completion messages, by examining the w Par am message argument. 

If the asynchronous operation could not be initiated, rVSAAsyncServByNameO returns 
a zero value, and a specific error number may be retrieved by calling 
WSAGetJLastErrorO. 



Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a hoscent structure together with the contents of data areas referenced by 
members of the same ho&tent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGJb l HOSTSTRUCT 
bytes (as defined in winsock Ji). 



Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, (he 
Windows Sockets implementation must re- post that message as long as the window 
exists. 



Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the IParam in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

As described above, they may be extracted from the IP or am in the reply message using 
the WSAGETAS YNCERROR macro 



WS AENETDO WN The W indows Sockets implementation has detected 

that the network subsystem has failed. 

WSAENOBUFS No/Insufficient buffer space is available 
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WSAHOST_NOT_FOUND 
WSATRY_ AGAIN 

WS ANO.RECO VER Y 

WSANO.DATA 



Authoritative Answer Host apt found. 

Non- Authoritative Host not found, or 
SERVERFAJL. 

Noq recoverable errors, FORMERR. REFUSED. 
NOTIMP. 

Valid name, no data record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be undated. 



WSANOnNTTTALISED 



WSAENETDOWN 



WSAEENPROGRESS 



WSAEWOULDBLOCK 



A successful YVSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this time due to resource or other constraints within 
the Windows Sockets implementation. 



See Also 



getservbynameO. WSACancelAsyncRequestQ 



35 



40 



45 



SO 



55 



BNSOOCID <EP 077095SA1 I > 



98 



EP 0 770 958 A1 



WSAAsyncGetServByPort as 

4.3.6 WSAAsyncGetServByPort() 

DesCflptl n Gee service information correspooding to a port and protocol - asynchronous version. 
# in elude <winsock.h> 

HANDLE PASCAL FAR WSAAsyucGetServByPort ( HWND hWnd, 

unsigned int *>Msg t iot port, const char FAR * prow, char FAR " buf 9 int buflen ); 

hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

wMsg The message to be received when the asynchronous request 

completes. 

port The port for the service, in network byte order. 

proto A pointer to a protocol name. This may be NULL, in which case 

WSAAsyncCetServByPortO will search for the first service entry for 
which s j>ort match the given port. Otherwise 
WSAAsyncGetServByPortO matches both port and proto. 

buf A pointer to the data area to receive the servent data. Note that this 

must be larger than the size of a servent structure. This is because the 
data area supplied is used by the Windows Sockets implementation to 
contain not only a servent structure but any and ail of the data which 
is referenced by members of the servent structure. It is recommended 
that you supply a buffer of MAXGETHOSTSTRUCT bytes. 

buflen The size of data area buf above. 

Remarks This function is an asynchronous version of getservbyportO. and is used to retrieve 
service information corresponding to a port number. The Windows Sockets 
implementation initiates the operation and returns to the caller immediately, passing 
back an asvpchropr»i< t*%)r hunHl* which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window HWnd receives 
message wMsg. The wParam argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of IParam contain any error 
code. The error code may be any error as defined in winaockJi. An error code of zero 
Indira trs successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call a servent structure. 

To access the elements of this s true aire, the original buffer address should be cast to a 
servent structure pointer and accessed as appropriate. 

Note that if the error code is WSAJENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IParam contain the size of buffer required 
to supply ALL the requisite information. If the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetServByPortO function call with a 
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buffer large enough to receive all the desired information (i.e. no smaller than the low 
! 6 bits of IP arum). 

The error code and buffer length should be extracted from the IParam using the macros 
WSAGETASYNCERROR and WS AG ETAS YNCB UFLEN . defined in winsockJj as: 

^define WSAGETASYNCERROR ( IParam) 
^define WSAGETAS YNCBUFLEN ( IParam) 



HIWORD (IParam) 
LOWORD (IParam) 



Return Value 



The use of these macros will maximize the portability of the source code for the 
application. 

The return value specifies whether or not the asynchronous operation was successfully 
initiated. Note that it does aoi imply success or failure of the operation itself. 

If the operation was successfully initiated, WSAAsyncGetServBjPortO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACanceiAsyncRequestO. It can also be used to match up asynchronous operations 
and completion messages, by examining the wParam message argument. 

If the asynchronous operation could not be initiated. WSAAsyncGetServByPortO 
returns a zero value, and a specific error number may be retrieved by filing 
WSAGctLastEnrorO. 

The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a servent structure together with the contents of data areas referenced by 
members of the same servent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in wiosock.h). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation re-post that message as long as the window 
exists. 



Comments 



Error Codes 



Windows Sockets suppliers should use the WS AMAKEASYNCREFLY macro when 
constructing the IParam in the message. 

The following error codes may be set when an application window receives a message. 
As described above, they may be extracted from Ok IParam in the reply message usina 
the WSAGETASYNCERROR macro. 



WSAENETDOWN 

WSAENOBUFS 
WSAHOST.NOT.FOUND 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

No/insufficient buffer space is available 

Authoritative Answer Host not found. 
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WSATRY.AGAIN 
WS ANO.RECO VER Y 
WSANO.DATA 



Son- Authoritative Host not found, or 
SERVERFAJL. 

Noa recoverable errors, FORMERR. REFUSED 
NOTIMP. 

Valid name, qo data record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WS ANOTENITLALISED 
WSAENETDOWN 
WSAEINPROGRESS 
WSAEWOULDBLOCK 



A successful WSAStartapO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this time due to resource or other constraints within 
the Windows Sockets implementation. 
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getservbyportO. WSACancelAsyncRequestQ 
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4.3.7 WSAAsyncSelect() 

Description Request event notification for a socket. 



^include <winsock.h> 



int PASCAL FAR WSAAsyncSelect ( SOCKET 5, HWND hWnd, 
unsigned int wMsg t long (Event ); 



s A descriptor identifying the socket for which event notification is 

required. 

HWnd A handle identifying the window which should receive a message 

when a network event occurs. 

"Msg The message to be received when a network event occurs. 

IE vent A bitmask which specifies a combination of network events in which 

the application is interested. 

Remarks This function is used to request that the Windows Sockets DLL should send a message 
to the window hWnd whenever it detects any of the network events specified by the 
(Event parameter. The message which should be sent is specified by the wMsg 
parameter. The socket for which notification is required is identified by s. 

This function automatically sets socket s to non-blocking mode. 



The (Event parameter is constructed by oring any of the values specified in the 
following List 



Value 



Meaning 



FD.READ Want to receive notification of readiness for reading 

FD_WRJTE Want to receive notification of readiness for writing 

FD_OOB Want to receive notification of the arrival of out-of -band data 

FD.ACCEFT Want to receive notification of incoming connections 

FD.CONNECT Want to receive notification of completed connection 

FD.CLOSE Want to receive notification of socket closure 



Issuing a WSAAsyocSelectO for a socket carrals any previous WSAAsyncSetectO for 
the same socket For example, to receive notification for both reading and writing, the 
application must call WSAAsyncSelectO with both FD.READ and FD.WRTTE. as 
follows: 

rc - WSAAsyncSelect (s, hWnd, wMsg, FD_READ I FD_WRITE) ; 

It is not possible to specify different messages for different events. The following code 
will not work: the second call will cancel the effects of the first, and only FD.WRITE 
events will be reported with message wMsg2: 

rc - WSAAsyncSelect (s, hWnd, wMsgl, FD_R£AD) ; 
rc - WSAAsyncSelect (s, hWnd, wMsg2, FD_WRITE) ; 
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To cancel all notification - i.e.. to indicate that the Windows Sockets implementation 
should send oo further messages related to network events on the socket - lEvcnt should 
be set to zero. 

rc =* WSAAsyncSelect (s, hWnd, 0, 0); 

Although in this instance WSAAsyncSelectO immediately disables event message 
posting for the socket, it is possible that messages may be waiting in the application's 
message queue. Toe application must therefore be prepared to receive network event 
messages even after cancellation. Cosing a socket with closesocketO also cancels 
WSAAsyncSelectO message sending, but the same caveat about messages in the queue 
prior to (he closesocketO still applies. 

Since an acceptO'ed socket has the same properties as the listening socket used to 
accept it. any WSAAsyncSelectO events set for the listening socket apply to the 
accepted socket. For example, if a listening socket has WSAAsyncSelectO events 
FD ACCEPT. FDJREAD, and FD_ WRITE, then any socket accepted on that listening 
socket will also have FD_ ACCEPT. FDJIEAD. and FD_WRITE events with the same 
wMsg value used for messages. If a different wMsg or events axe desired, the 
application should call WSAAsyncSelectO. passing the accepted socket and the desired 
new information, 7 

When one of the nominated network events occurs on the specified socket r. the 
application's window hWnd receives message wMsg. The wParam argument identifies 
the socket on which a network event has occurred. The low word of IP or am specifies 
the network event that has occurred. The high word of IP or am contains any error code. 
The error code be any error as defined in wtnsockJi. 

The error and event codes may be extracted from the IP or am using the macros 
WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in winsock-h as: 
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Idefine WSAGETSELECTERROR (IP a ram) 
♦define WSAGETSELECTEVENT C IP a ram) 



HIWORD(lParam) 
LOWORD(lParam) 



40 



The use of these macros will maximize the portability of the source code for the 
application. 

The possible network event codes which may be returned are as follows: 



45 



Value 



Mowing 



FD_READ Socket s ready for reading 

FD_WRTTE Socket s ready for writing 

FD_OOB Out-of-band data ready for reading oo socket s. 

FD_ ACCEPT Socket s ready for accepting a new incoming connection 

FD.CONNECT Connection on socket s completed 

FdIcLOSE Connection identified by socket s has been closed 
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7 Note that there is a >*mm g window between the acceptO call and the call to WSAAsyncSelectO to 
change the events or wMsg. An application which desires a different wSfsg for the listening and 
acceptO'ed sockets should ask for only FD.ACGEPT events on the listening socket, then set appropriate 
events after the acceptO. Since FD_ACCEPT is never sent for a connected socket and FDJIEAD. 
FD_ WRITE, FD_OOB. and FD.CLOSE are never sent for listening sockets, this will not impose 
difficulties. 
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Return Value 



Comments 



The return vaiue is 0 if the application's declaration of interest in the network event set 
was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error 
number may be retrieved by calling WSAGetLastErrorO- 

Although WSAAsyacSelectO can be called with interest in multiple events, the 
application window will receive a single message for each network event. 

As in the case of the selectO function. WSAAsyncSelectO will frequently be used to 
determine when a data transfer operation (sendO or recvO) can be issued with the 
expectation of immediate success. Nevertheless, a robust application must be prepared 
for the possibility that it may receive a message and issue a Windows Sockets API call 
which returns WSAEWOULD BLOCK immediately. For example, the following 
sequence of events is possible: 



(i) 

(ii) 
(iii) 

(iv> 
(v) 

(vi) 



data arrives on socket s; Windows Sockets posts WSAAsyncSelect 
message 

application processes some other message 

while processing, application issues an ioctisocketfs, FIONREAD.-) 

and notices that there is data ready to be read 

application issues a recv(a^ M ) to read the data 

application loops to process next message, eventually reaching the 

WSAAsyncSelect message indicating that data is ready to read 

application issues rccv(s*...). which fails with the error 

WSAEWOULDBLOOC 



Other sequences are possible. 

The Windows Sockets DLL will not continually flood an application with messages for 
a particular network event. Having successfully posted notification of a particular event 
to an application window, no further messaged) for that network event will be posted to 
the application window until the application makes the function call which implicitly 
reeoables notification of that network event 
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FD.READ 

FD_ WRITE 

FD.OO B 

FD_ACCEPT 

FELCONNECT 

FD.CLOSE 



Rg^nnhlintr fnnrrinn 



recvO or recvfrotnO 
sendO or sendtoO 
recvO 
acceptO 

NONE 
NONE 



Any call to the reenabling routine, even one which fails, results in reenabling of 
message posting for the relevant event 

For FD.READ. FD_OOB . and FD_ACCEFT events, nv»S Tft ge posting is "level- 
triggered.** This means that if the reenabling routine is ™n»/j g£d the relevant event is 
still valid after the call, a WSAAsyncSefectO message is posted to the application. 
This allows an application to be event-driven and not concern itself with the amount of' 
data that arrives at any one time. Consider the following sequence: 



55 



BNSDOCIO <EP 0770958A1 1 > 



104 



EP 0 770 958 A1 



WSAAsyncSel ct 91 



(i) 

(u) 
(iii) 



Windows Sockets DLL receives 100 bytes of data on socket s and 
posts an FD JtEAD message. 

The appUcatioo issues recv( s. bufTptr, 50, 0) to read 50 bytes. 
The Windows Sockets DLL posts another FD_READ message sin r*» 
there is still data to be read. 
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With these semantics, an application need not read all available data in response to an 
FD_READ message- a single recvO in response to each FD.READ message is 
appropriate. If an application issues multiple recvO calls in response to a single 
FD_R£AD. it may receive multiple FD_READ messages. Such an application may 
wish to disable FD_R£AD messages before starting toe recvO calls by calling 
WSAAsyncSelectO with the FD.READ event not set. 

If an event is true when the application initially calls WSAAsyncSelectO or when the 
reenabling function is called, then a message is posted as appropriate. For example, if 
an application calls tistenO. a connect attempt is made, then the application calls 
WSAAsyncSelectO specifying that it wants to receive FD_ACCEFT messages for the 
socket, the Windows Sockets implementation posts an FD.ACGEPT message 
immediately. 

The FD_ WRITE event is handled slightly differently. An FD.WRJTE message is 
posted when a socket is first connected with connectO or accepted with acceptO. and 
then after a seodO or sendtoO fails with WSAEWOULDBLOCK and buffer space 
becomes available. Therefore, an application can assume that sends are possible 
starting from the first FD.WRTTE message and lasting until a send returns 
WSAEWOULDBLOCK. After such a failure the application will be notified that sends 
are again possible with an FD.WRITE message. 

The FD.OOB event is used only when a socket is configured to receive out-of-band 
data separately. If the s ock et is configured to receive out-of-band data in-line, the out- 
of-band (expedited) data is treated as normal data and the application should register an 
interest in, and will receive. FD.READ events, noi FD.OOB events. An application 
may set or inspect the way in which out-of-band data is to be h«nrf^ by using 
setsockoptO or getsockoptO for the SO.OOB INLINE option. 

The error code in an FD_ CLOSE message indicates whether the socket close was 
graceful or abortive. If the error code is 0. then the close was graceful; if the error code 
is WSAECONNRESET. then the socket's virtual socket was reset This only applies to 
sockets of type SOCK.STREAM. 

The FD_CLOSE message is posted when a close indication is received for the virtual 
circuit corresponding to the socket. In TCP terms, this means that the FD.CLOSE is 
posted when the connection goes into the FIN WATT or CLOSE WATT states. This 
results from the remote end performing a sbutdownO on the send side or a 
closesocketO- 
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Please note your application will receive ONLY an FD.CLOSE message to indicate 
closure of a virtual circuit. It will NOT receive an FD.READ message to indicate this 
condition. 



Error Codes WSANOTTNITLALiSED 



A successful WSAStartupO must occur before 
using mis APL 
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WSAENCTDOWN 

WSAETNTVAJL 

WSAEINPROGRESS 



The Windows Sockets implementation has detected 
chat the network subsystem has failed. 

Indicates that one of the specified parameters was 
invalid 

A blocking Windows Sockets operation is in 
progress. 



Additional error codes may be set when an application window receives a message. 
This error code is extracted from the IP or am in the reply message using the 
WSAGETSELECTERROR macro. Possible error codes for each network event are 
Event: RECONNECT 

Error Code Mining 



WSAEADDRINUSE 
WSAEADDRNOTAVAXL 

WSAEAFNOSUPPORT 

WSAECONNREFUSED 

WSAEDESTADDRREQ 

WSAEFAULT 

WSAEINVAL 

WSAEISCONN 

WSAEMFILE 

WSAENETUNREACH 

WSAENOBUFS 

WSAENOTCONN 
WSAENOTSOCK 
WSAFTTMEDOUT 



Event: FD.CLOSE 
Error Code 



WSAJENETDOWN 
WSAECONNRESET 



The specified address is already in use. 

The specified address is not available from the local 

Addresses in the specified family cannot be used 
with this socket. 

The attempt to connect was forcefully rejected. 

A destination address is required. 

The nameien argument is incorrect 

The socket is already bound to an address. 

The socket is already connected. 

No more file descriptors are available. 

The network can't be reached from this host at this 
time. 

No buffer space is available. The socket cannot be 
connected. 

The socket is not connected. 

The descriptor is a file, not a vrkpt 

Attempt to connect timed out without establishing a 
connection 

Mining 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The connection was reset by the remote side. 
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WSAECONN ABORTED 



The connection was aborted due to timeout or other 
fall are . 
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Event: FD.READ 
Event: FD_ WRITE 
Event: FD.OOB 
Event: FD.ACCEPT 
Error Code 



WSAENETOOWN 



Mf>anin f 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 
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Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets Supplier to ensure that messages are 

successfully posted to the application. If a PostMessageO operation fails, the Windows 
Sockets implementation NiUST re -post that message as long as the window exists. 

Windows Sockets suppliers should use the WS AMAKESELECTREPLY macro when 
cons true ring the IParom in the message. 

When a socket is closed, the Windows Sockets Supplier should purge any messages 
remaining for posting to the application window. However the application must be 
prepared to receive, and discard, any messages which may have been posted prior to the 
closesocketO 
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See Also 



selectO 
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4.3.8 WSACanc IA yncReque t() 

Description Cancel an incomplete asynchronous operation. 

^include <wiosock.b> 

iot PASCAL FAR WSACancelAsyncRe^uest ( HANDLE hAsyncTaskHandle ); 
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Remarks 



Return Value 



Comments 



hAsyncTaskHandle Specifies the asynchronous operation to be canceled. 

the WSACancelAsyncReqiiestO function is used to cancel an asynchronous operation 
which was initiated by one of the WS AAsyncG etXBy YQ functions such as 
WSAAsyocGetHostByNameO. The operation to be canceled is identified by the 
hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as 
returned by the initiating function. 

The value returned by WSACancelAsyncRequestO is 0 if the operation was 
successfully canceled. Otherwise the value SOCKET_ERROR is reamed and a 
specific error number may be retrieved by calling WSAGetLastErrorO. 

An attempt to cancel an existing asynchronous WSAAsyncGetXBy YO operation can 
fail with an error code of WSAEALREAD Y for two reasons. First, the original 
operaoon has already completed and the application has dealt with the resultant 
message. Second, the original operation has already completed but the resultant 
message is soil waiting in the application window queue. 



Notes For 
Windows Sockets 



Suppliers 



Hi ^paTp^T V Ut ^ a can us ^y distinguish between WSAQNVAL 
and WSAEALREAD Y. since in both cases the error indicate that there is no 
asynchronous operation in progress with the indicated handle. (Trivial exception; 0 is 
always an invalid asynchronous task handle ] The Windows Sockets specification does 
not prescribe how a conformant Windows Sockets implementation should disoMiiish 
between the two cases. For maximum portability, a Windows Sockets application 
should treat the two errors as equivalent 



Error Codes WSANOTTNTIIALISED 
WSAENETDOWN 
WSAEINVAL 
WSAEINPROCRESS 
WSAEALREADY 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Indicates that the specified asynchronous task handle 
was invalid 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous routine being rj^H has 
already completed. 
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5 See Also WSAAsyncGetHostByAddrO. WSAAsyocCetHostByNamcO. 

WSAAsyncGctProt ByNumberO. WSAAsyncG tProtoByNameO. 
WSAAsyDcGctHostByNamcO. WSAAsyncGetServByPortO. 
I WSAAsyncGctServByNameO. 
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4.3.9 WSACancelBI cklngCall() 

Description Cancel a blocking call which is currently in progress, 
^include <wiosock.h> 
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int PASCAL FAR WSACancelBlockingCall ( void ); 

Remarks This function cancels any outstanding blocking operation for this task. It is normally 
used in two situations: 

(1) An application is processing a message which has been received while a blocking 
call is in progress. In this case. WSAIsBlockingO will be true. 

(2) A blocking call is in progress, and Windows Sockets has called back to (he 
application's "blocking hook'' function (as estabUshed by VVSASetfilockiogHookO). 

In each case, the original blocking call will terminate as soon as possible with the error 
WSAEINTR. (In (l). the termination will not cake place until Windows message 
scheduling has caused control to revert to (he blocking routine in Windows Sockets In 
(2). the blocking call will be terminated as soon as the blocking hook function 
completes.) 

In the case of a blocking connectO operation, the Windows Sockets implementation 
will terminal* the blocking call as soon as possible, but it may not be possible for the 
socket resources to be released until the connection has completed (and then been reset) 
or timed oul This is likely to be noticeable only if the application immediately tries to 
open a new socket Of no sockets are available), or to connectO to the same peer. 

Canr H l i ng an acceptO or a selectO call does not adversely impact the sockets passed to 
these calls. Only the particular call fails: any operation that was legal before the cancel 
is legal after the cancel, and the state of the socket is not affected in any way. 

Canc e lling any operation other than acceptO and selectO can leave the socket in an 
iiide terminate state. If an application cancels a blocking operation on a socket, the only 
operation that the application can depend on being able to perform on the socket is a 
call to dosesocketO. although other operations may work on some Windows Sockets 
implementations. If an application desires maximum portability, it must be careful not 
to depend on performing operations after a cancel. An application may reset the 
conne cti o n by setting the timeout on SO_UNGER to 0. 

If a cancel operation compromised the integrity of a SOOCSTREAKs data stream in 
any way. the Windows Sockets implementation must reset the connection and fail all 
future operations other than dosesocketO with WSAECONN ABORTED. 



Return Value 



Comments 



The value returned by WSACancelBlockingCaJIO is 0 if the operation was 
successfully canceled. Otherwise the value SOOCET_ERROR is returned, and a 
specific error number may be retrieved by calling WSAGetLastErrorO. 

Note that it is possible that the network operation completes before the 
WSACancelBlockingCallO ts processed, for example if data is received into the user 
buffer at interrupt time while the application is in a blocking hook. In this case, the 
blocking operation will return successfully as, if WSACancelBlockingCallO had never 
been called. Note that the WSACancelBlockingCaUO soil succeeds in this case; the 
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ooly way to know with certainty that an ope ratio a was actually canceled is to check for 
a return code of WSAEINTR from the blocking call. 



Error Codes WSANOTTNITIALISED 
10 WSAENETOOWN 

WSAEINVAL 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation hac detected 
that the network subsystem has failed. 

Indicates that there is no outstanding blocking call. 
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4.3.10 WSACIeanup() 

Description Terminate use of the Windows Sockets DLL. 
#include <winsock.b> 



w 



15 



20 



25 



30 



35 



40 



Remarks 



mt PASCAL FAR WSACIeanup ( void ); 

An application or DLL is required to perform a (successful) WSAStartupO caU before 
it can use Windows Sockets services. When it has completed the use of Windows 
Sockets, the application or DLL must call WSACleanupO to deregister itself from a 
Windows Sockets implementation and allow the implementation to free any resources 
allocated on behalf of the application or DLL. Any open SOCX.STREAM sockets that 
axe connected when WSACleanupO is called are reset; sockets which have been closed 
with closesocketO but which still have pending data to be sent are not affected -the 
pending data is still sent 

There must be a call to WSACleanupO for every call to WSAStartupO made by a 
task. Only the final WSACleanupO for that task does the actual cleanup: the preceding 
calls simply decrement an internal reference count in the Windows Sockets DLL. A 
naive application may ensure that WSACleanupO was called enough times by calling 
WSACleanupO in « loop until it returns WSANOTTNTTTALISED. 

The return value is 0 if the operation was successful Otherwise the value 
SOCKET_ERROR is returned, and a specific error number may be retrieved by calling 
WSAGetLaatErrorO. 

Attempting to call WSACleanupO from within a blocking hook and then failing to 
check the return code is a common Windows Sockets programming error. If an 
application needs to quit while a blocking call is outstanding, the application must first 
cancel the blocking call with WSACancelfilockingCallO then issue the 
WSACleanupO call once control has been returned to the application. 

Notes For 
Windows Sockets 

Suppliers Well-behaved Windows Sockets applications will make a WSACleanupO call to 
indicate dercgistration from a Windows Sockets implementation. This function can 
thus, for example, be utilized to free up resources allocated to the specific application. 

A Windows Sockets implementation must be prepared to deal with an application 
which terminates without invoking WSACleanupO - for example, as a result of an 



Return Value 



Comments 



so 



In a multithreaded environment. WSACleanupO terminates Windows Sockets 
operations for all threads. 

A Windows Sockets implementation must ensure that WSACleanupO leaves things in 
a state in which the application can invoke WSAStartupO to re-establish Windows 
Sockets usage. 



Error Codes WSANOTENTTIALISED 



A su ccessful WSAStartupO must occur before 
using this APL 
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WSAENETDOWN 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 



WSAEINPROGRESS 



10 



A blocking Windows Sockets operation is in 
progress. 



See Also WSAStartupO 
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20 



2S 



4.3.11 WSAGetLastErrorO 

Description Get the error status for the last operation which failed. 

^include <winsock.h> 

| int PASCAL FAR WSAGetLastError ( void ); 

Remarks This function returns the last network error that occurred. When a particular Windows 

Sockets API function indicates that an error has occurred, this function should be called 
to retrieve the appropriate error code. 

Return Value The return value indicates the error code for the last Windows Sockets API routine 
performed by this thread. 

Notes For 
35 Windows Sockets 

Suppliers The use of the WSAGetLastErrorO function to retrieve the last error code, rather than 
relying on a global error variable (cf. errno), is required in order to provide 
compatibility with future multi- threaded environments. 

40 | Note that in a nonpreemptive Windows environment WSAGetLastErrorO is used to 

retrieve only Windows Sockets API errors. In a preemptive environment, 
WSAGetLastErrorO will invoke GetLastErrorO* which is used to retrieve the error 
status for all Win32 API functions on a per- thread basis. For portability, an application 
should use WSAGetLastErrorO imm^HiflfHy after the Windows Sockets API function 

45 which failed. 

See Also WSASetLastErrorQ 
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4.3.12 WSAIsBlocklngO 

Description Determine if a blocking call is in progress, 
^include <wiusock.h> 



10 



15 



20 



25 



30 



Remarks 



Return Value 



Comments 



BOOL PASCAL FAR WSAIsBlocking ( void ); 

This function allows a task to determine if it is executing while waiting for a previous 
blocking call to complete. 

The return value is TRUE if there is an outstanding blocking function awaiting 
completion. Otherwise, it is FALSE. 

Although a call issued on a blocking socket appears to an application program as 
though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow 
other applications to run. This means that it is possible for the application which issued 
the blocking call to be re-entered, depending on the message(s) it receives. In this 
instance, the WSAIsBlockingO function can be used to ascertain whether the task has 
been re-entered while waiting for an outstanding blocking call to complete. Note that 
Windows Sockets prohibits more than one outstanding call per thread. 

Notes For 
Windows Sockets 

Suppliers A Windows Sockets implementation must prohibit more than one outstanding blocking 
call per thread. 
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4.3.13 WSASetBlocklngH k(; 

Description Establish an application- specific blocking hook function. 
# include <winsock.Q> 

FARPROC PASCAL FAR WSASetBlockingHook ( FARPROC IpBlockFunc ); 



tpBlockfunc A pointer to the procedure instance address of the blocking function to 
be installed. 

Remarks This function installs a new function which a Windows Sockets implementation should 

use to implement blocking socket function calls. 

A Windows Sockets implementation Includes a default mechanism by which blocking 
socket functions are implemented. The function WSASetBlockingHookO gives the 
application the ability to execute its own function at "blocking * time in place of the 
default function. 

When an application invokes a blocking Windows Sockets API operation, the Windows 
Sockets implementation initiates ihe operation and then enters a loop which is similar to 
the following pseudocode: 

for<;;) { 

/* flush messages for good user response */ 
while (BlockingHook ( ) ) 

r 

/* check for WSACancelBlockingCall ( ) */ 
if (operation_cancelled() ) 
break; 

/* check to see if operation completed */ 
i f (operation_coraplete ( ) ) 

break; /• normal completion */ 

1 

Note that Windows Sockets implementations may perform the above steps in a different 
order: for example, the chfrfr for operation complete may occur before calling the 
blocking hook. The default BlockingHookO function is equivalent to: 

BOOL DefaultBlockingHook (void) { 
MSG msg; 
BOOL ret; 

/* get the next message if any */ 

ret - (BOOL)PeekMessage(imsg^LL,0 / 0,PM_R£M0VE) ; 

/* if we got one, process it */ 

if (ret) ( 

Trans lateMessage (&msg) ; 

DispatchMessage (irtLsg) ; 

) 

/* TRUE if we got a message •/ 
return ret; 

) 

The WSASetBlockingHookO function is provided to support those applications which 
require more complex message processing - for example, those employing the MDl 
(multiple document interface) model. It is afii intended as a mechanism for performing 
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Return Value 



general applications functions. In particular, the only Windows Sockets API function 
which may be issued from a custom blocking hook function is 
WSACancelBlockiagCaJlO. which will cause the blocking loop to terminate. 

This function must be implemented on a per-task basis for non-multithreaded versions 
of Windows and on a per- thread basis for multithreaded versions of Windows such as 
Windows NT. It thus provides for a particular task or thread to replace the blocking 
mechanism without affecting other tasks or threads. 

In multithreaded versions of Windows, there is no default blocking hook-blockin* calls 
block the thread that makes the call However, an application may install a soecific 
blocking hook by calling WSASetBloclcingHookO- 

This allows easy portability of applications that depend on the blocking hook behavior. 

The return value is a pointer to the procedure-instance of the previously installed 
blocking function. The appdcation or library that calls the WSASetBlockingHook 0 
function should save this return value so that it can be restored if necessary (If 
"nesting" is not important, the application may simply discard the value returned by 
WSASetBIockiogHookO and eventually use WS A Un hook B lock in gHook 0 to restore 
the default mechanism.) If the operation fails, a NULL pointer is returned, and a 
specific error number may be retrieved by calling WSAGetLastErrorO. 



Error Codes WSAJS'OTTNTTIALISED 



WSAENETDOWN 



See Also 



WSAJEINFROGRESS 



WSAUohookBlockiogHookO 



A successful WSAStartupO must occur before 
using this AFL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 
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4.3.14 WSASetLastError() 

De script I n Set the error code which can be retrieved by WSAGetLastErTorO- 
# include <wiosock.h> 



w 



void PASCAL FAR WSA Set Last Error ( int iError ); 



75 



Remarks This functioo allows an application to set the error code to be returned by a subsequent 
WSAGetLastErTorO call for the current thread. Note that any subsequent Windows 
Sockets routine called by the application will override the error code as set by this 
routine. 



iError Specifies the error code to be returned by a subsequent 

WSAGetLastErTorO call. 

Notes For 
Windows Sockets 

Suppliers In a Win32 environment, this function will Invoke SctLastErrorQ. 



25 Return Value None. 



'30 



Error Codes WSANOTTNITTALISED A successful WSAStartupO must occur before 

ming fhtg APL 

See Also WSAGetLastErrorO 
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4.3.15 WSAStartup() 
Description 



10 



#include <winsock.h> 

int PASCAL FAR WSAStartup ( WORD wVersionRequested % 
LPWSADATA IpWSAData ); 
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Remarks 



IpWSAData 



wVenionRequested The highest version of Windows Sockets API support that the 
caller can use. The high order byte specifies the minor 
version (revision) number: the low-order byte specifies the 
major version number. 

A pointer to the WSADATA data structure that is to receive 
details of the Windows Sockets implementation. 

This function MUST be the first Windows Sockets function called by an application or 
DLL. It allows an application or DLL to specify the version of Windows Sockets API 
required and to retrieve details of the specific Windows Sockets implementation. The 
application or DLL may only issue further Windows Sockets API functions after a 
successful WSASUrtupO invocation. 

In order to support future Windows Sockets implernenutions and applications which 
may have functionality differences from Windows Sockets 1.1. a negotiation takes 
place in WSAStartupQ. The caller of WSASUrtupO and the Windows Sockets DLL 
indicate to each other the highest version that they can support and each confirms that 
the other's highest version is acceptable. Upon entry to WSASUrtupO. the Windows 
Sockets DLL examines the version requested by the application. If mis version is 
higher than the lowest version supported by the DLL, the call succeeds and the DLL 
returns in wHighVersion the highest version it supports and in "Version the minimum 
of its high version and wVersionRequested. The Windows Sockets DLL then assumes 
that the application will use wVersion. If the wVersion field of the WSADATA 
structure is unacceptable to the caller, it should call WSACleanupO and either search 
for another Windows Sockets DLL or fail to tnitialiie. 

This negotiation allows both a Windows Sockets DLL and a Windows Sockets 
application to support a range of Windows Sockets versions. An application can 
successfully utilize a Windows Sockets DLL if there is any overlap in the version 
ranges. The following chart gives examples of how WSASUrtupO works in 
conjunction with different application and Windows Sockets DLL versions: 





DLL Version* 




w version 






1.1 


1.1 


11 


LI 


LI 


use I I 


1.0 1.1 


1.0 


II 


1.0 


LO 


xac 10 


1.0 


10 II 


1.0 


to 


LI 


use 1.0 


1.1 


1.0 (.1 


1.1 


LI 


LI 


use l.l 


1.1 


10 


1.1 


to 


1.0 


AppUouioo fftiia 


1.0 


1.1 


10 






WSAVHLSOTSUPPORTTD 


1.0 1.1 


10 i.i 


11 


LI 


LI 


use LI 


1.1 2.0 


1.1 


2.0 


II 


LI 


u~ LI 


2.0 


It 


2.0 


LI 


LI 


Application fails 
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The following code fragment demonstrates how an application which supports only 
version 1.1 of Wind w$ Sockets makes a WSASUrtupO call: 

WORD wVersionRequested; 
WSADATA wsaDaca; 
int err; 

wVersionRequested = MAK£W0RD( 1, 1 ); 

err = WSAStartup ( wVersionRequested, iwsaData ); 

if ( err != 0 ) ( 

/* Tell the user that we couldn't find a useable */ 
/• winsock.dll. */ 
return; 

\ 

/* Confirm that the Windows Sockets DLL supports 1.1. •/ 
/* Note that if the DLL supports versions greater */ 
/* than 1.1 in addition to 1-1, it will still return */ 
/* 1.1 in wVersion since that is the version we */ 
/* requested. ♦/ 

if ( LOBYTE ( wsaData. wVersion ) !- 1 M 

H IBYTE ( wsaData. wVersion > !- 1 ) { 
/• Tell the user that we couldn't find a useable */ 
/* winsock.dll. */ 
WSACleanup( ); 
return; 

1 

/* The Windows Sockets DLL is acceptable. Proceed. •/ 

And this code fragment demonstrates how a Windows Sockets DLL which supports 
only version 1.1 performs the WSAStartupO negotiation: 

/* Make sure that the version requested is >- 1.1. •/ 
/* The low byte is the major version and the high •/ 
/* byte is the minor version. */ 

if ( LOBYTE ( wVersionRequested ) < 1 II 

( LOBYTE ( wVersionRequested ) — 1 && 
a IBYTE ( wVersionRequested ) < 1 ) { 
return WSAVXRNOTSOPPORTED; 

} 

/* Since we only support 1.1, set both wVersion and •/ 
/* wHighVersion to 1.1. */ 

lpWsaData->wVersion - MAKEWORIM 1, 1 ) ; 
lpWsaData->wHighVersion - MAKEWORD ( 1, 1 ) ; 

Once an application or DLL has made a successful WSAStartupO call, it may proceed 
to make other Windows Sockets API calls as needed. When it has finished using 
services of the Windows Sockets DLL. the application or DLL must call 
WSACleanupO in order to allow the Windows Sockets DLL to free any resources for 
the application. 
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Details of che acrual Windows Sockets implementation are described in the WSAData 
structure defined as foUows: 



struct WSAData { 
WORD 
WORD 
char 
char 

unsigned short 
unsigned short 
char TAR • 

\; 



"Version; 
wHighVersion; 

szOescript ion(WSADESCRlPTION LEN+1] 

S2SyscemStacus(WSASYSSTATUS LEN^-ll • 
iMax Socket s; 

iMaxUdpDg; 

LpVendorrnfo; 



The members of 

Element 

w Version 



this structure are: 

Usage 



wHighVersion 



szDescription 



szSystemStaais 



iMaxSockets 



iMaxUdpDg 



The version of the Windows Sockets specification that the Windows 
Sockets DLL expects the caller to use. 

The highest version of the Windows Sockets specification that this 
DLL can support (also encoded as above). Normally this w ill be the 
same as wVersion. 

A null-terminated ASCII string into which the Windows Sockets DLL 
copies a description of the Windows Sockets implementation 
including vendor identification. The text (up to 256 characters in 
length) may contain any characters, but vendors are cautioned against 
including control and formatting characters: the most likely use that 
an application will put this to is to display it (possibly truncated) in a 
status message. 

A miU-tenninated AS CD string into which the Windows Sockets DLL 
copies relevant status or configuration information. The Windows 
Sockets DLL should use this field only if the information might be 
useful to the user or support staff: it should not be considered as an 
extension of the szDescription field. 

The maximum number of sockets which a single process can 
potentially open. A Windows Sockets implementation may provide a 
global pool of sockets for allocation to any process: alternatively it 
may allocate per-process resources for sockets. The number may well 
reflect the way in which the Windows Sockets DLL or the networking 
software was configured Application writers may use this mimbeTa? 
a crude indication of whether the Windows Sockets implementation is 
usable by the application. For example, an X Windows server might 
check iMaxSockets when first started: if it is less than 8. the 
application would display an error message instructing the user to 
reconfigure the networking software. (This is a situation in which the 
szSystemStatus text might be used.) Obviously there is no guarantee 
that a particular application can actually allocate iMaxSockets sockets 
since there may be other Windows Sockets applications in use 
The size in bytes of the largest UDP datagram that can be sent or 
received by a Windows Sockets application. If the implementation 
imposes no limit, iMaxUdpDg is zero. In many implementations of 
Berkeley sockets, there is an implicit limit of 8 192 bytes on UDP 
datagrams (which are fragmented if necessary). A Windows Sockets 
implementation may impose a limit based, for instance, on the 
allocation of fragment reassembly buffers. The minimum value of 
iMaxUdpDg for a compliant Windows Sockets unplementati n is 512 



120 



EP 0 770 958 A1 



WSAStartup 108 



w 



15 



20 



25 



30 



35 



Note that regardless of the value of iMaxUdpDg. it is inadvisable to 
attempt to send a broadcast datagram which is larger rh» n the 
Maximum Transmission Unit (MTU) for the network. (The Windows 
Sockets API does qoi provide a mechanism to discover the MTU. but 
it must be no less than 512 bytes.) 
Ip Vendorlnfo A far pointer to a vendor- specific data structure. The definition of 
this structure (if supplied) is beyond the scope of this specification. 

An application or DLL may call WSAStartupO more than once if it needs to obtain the 
WSAData structure information more than once. However, the wVersionRe quired 
parameter is assumed to be the same on ail calls to WSAStartupO: that is. an 
application or DLL cannot change the version of Windows Sockets it expects after the 
initial call to WSAStartupO. 

There must be one WSACIeanupO call corresponding to every WSAStartupO call to 
allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an 
application. This means, for example, that if an application calls WSAStartupO three 
times, it must call WSACIeanupO three times. The first two calls to WSACIeanupO 
do nothing except decrement an internal counter; the final WSACIeanupO call for the 
task does all necessary resource deallocation for the task. 



Return Value WSAStartupO returns zero if successful Otherwise it re turns one of the error codes 
listed below. Note mat the normal mechanism whereby the application calls 
WSAGetLastErrorO io determine the error code cannot be used, since the Windows 
Sockets DLL may not have established the client data area where the "last error" 
information is stored. 

Notes For 
Windows Sockets 

Suppliers Each Windows Sockets application MUST make a WSAStartupO call before issuing 
any other Windows Sockets API calls. This function can thus be utilized for 
initialization purposes. 

Further issues are discussed in the notes for WSACIeanupO. 
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Error Codes WSASYSNOTREADY 

WSAVERNOTSUPPORTED 

WSAETNVAL 
See AJSO sendO. sendtoO. WSACIeanupO 



Indicates that the underlying network subsystem is 
not ready for network communication* 



The version of Windows Sockets API support 
requested is not provided by this particular Windows 
Sockets implementation. 

The Windows Sockets version specified by the 
application is not supported by this DLL. 
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4.3.16 WSAUnhookBI cklngHook() 
Description Restore the default blocking hook function. 

^include <winsockJb> 

iat PASCAL FAR WSAUohookBiockingHook ( void ); 



Remarks 



Return Value 



This function removes any previous blocking hook thai has been installed and reinstalls 
the default blocking mechanism. 

WSAUnhookBIockiogHookO will always install the default m^h ^j^, not ^ 
OrCViflUfi mechanism. If an application wish to nest blocking hooks - i.e. to establish a 
temporary blocking hook function and then revert to the previous mechanism (whether 
the default or one established by an earlier WSASetBlockingHookO) - it must save and 
restore the value returned by WSASetBIockiogHookO: it cannot use 
WSAlfDhookBlockiogHookO. 

In multithreaded versions of Windows such as Windows NT. there is no default 
blocking hook. Calling WSAUnbookBlockingHookO disables any blocking hook 
installed by the application and any blocking calls made block the thread which made 
the call. 

The return value is 0 if the operation was successful Otherwise the value 
SOCKET.ERROR is returned, and a specific error number may be retrieved by calling 
WSAGetLastErrorO. 



Error Codes WS ANOTTNITIALISED 



A successful WSAStartupO must occur before 
using this API. 



See Also 



WSASetBlockingHookO 
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A ppendix A. Error Codes antf Header Files 
A.1 Error Codes 

The following is a list of possible error codes returned by the WSAGelLastEnrorO call, along with their 
explanations. The error numbers are consistently set across ail Windows Sockets-compliant 
implementations. 







Error 




e roro: at :or. 


W 5AE I NT 3 


E1NTR 


1 0 0 0 4 


Ad 


LA 


standard C 


WSAEBADr 


E3ADF 


10009 


AS 


in 


standard C 


WS AZACCIS 


EACCES 


LOO 1 2 


As 


i n 


standard C 


WSAEF AUlT 


EFAULT 


19014 


As 


in 


standard C 


WSAEISVAL 


EINVAL 


10022 


As 


in 


standard Z 


WSAEXFILE 


EHFILE 


10 024 


As 


in 


standard C 


WSAEWCULDBLOCK 


EWOULDBLCCK 


LOO JS 


As 


in 


BSD 


wsaeim? sccress 


EINPROGRZSS 


L003* 


This or roc is returned if any 








Windows Sockets API function is 








called while d blocking function is 








in 


progress . 


WSAXAlRiAOr 


EALREADY 




As 


in 


BSD 


WSA£NOTSCCK 


£ NOT SOCK 


L0Q 38 


AS 


in 


BSD 


WSAEOESTADDRREQ 


• DESTAODRR£Q 


L0039 


As 


i n 


BSD 


WSAEMSC3 IZZ 


EMSG3 IZE 


10040 


As 


in 


BSD 


WSA£?P.OTOTYPE 


EPROTOTYPE 


L004 1 


AS 


i n 


BSD 


WSAENOPROTOOPT 


ENOPROTOOPT 


L0042 


As 


in 


BSD 


WSAEPROT0NOSUPP0RT 


EPROTONOSUPPCRT 


10043 


As 


in 


BSD 


W5AES0CKTN0SUPPORT 


ESOCKTNOSUPPORT 


10044 


As 


in 


BSD 


WSAEOPNOTSUPP 


EOPNOTSUPP 


10045 


AS 


in 


BSD 


WSAEPrNOSUPPORT 


EPFNOSUPP0RT 


10046 


AS 


in 


850 


WSAEATNOSUPPORT 


EAFNOSUPPORT 


10041 


As 


in 


BSD 


WSAEAODRINUSE 


EAOORENUSE 


IC04 8 


As 


l n 


BSD 


WSAEA00RNOTAVAIL 


EADDRNOTAVA t 1 


ICO 4 9 


As 


l n 


BSD 


WSA£N£T0OWN 


ENETOOWN 


1 C050 


AS 


i n 


BSD. This error may be 








reported at any time if the Windows 








Sockets implementation detects an 








underlying failure. 


WSAENETL'NRIACH 


ENETUMRXACH 


1005 I 


As 


l n 


9SD 


WSA£N*XTR£SET 


c ^ » c e 
ENtTRtSE i 


10052 


AS 


l n 


BSD 


WSAECONNA SORTED 


cCUNMABOKT-O 


i fin *k i 


As 


i n 


9SD 


WS A£CONKR£S£T 


iv.ONniu.9LT 


10054 


As 


in 


BSD 


WSAENOBUFS 


EN08UFS 


10055 


As 


i n 


BS0 


WSA£ISCOKN 


EISC0NN 


10056 


As 


in 


350 


WSAENOTCONN 


ENOTCONN 


10057 


As 


i n 


3S0 


WSA£ SHUTDOWN 


ES HUT DOWN 


1005a 


As 


in 


350 


WSAETOOKANYREFS 


ETOOMANYREFS 


10039 


As 


i n 


BSD 


WSAETIMEDOUT 


ETIMEDOUT 


10060 


As 


in 


BSD 


WSA£COKNR£<US£0 


ECONNREFUSEO 


10061 


As 


in 


BSD 


WSAELOOP 


ELOOP 


10062 


As 


in 


aso 


WSAZNAMETOOLONG 


ENAMETOOLOKC 


10063 


AS 


in 


BSD 


WSAEHOSTDOWN 


EKOSTDOWN 


10064 


AS 


in 


BSD 


WSAEHOSTUNREACH 


EHOSTUNREACH 


10065 


As 


in 


BSD 


WSASYSNOTREADY 




10091 


Returned by t*SAJt*rtup () 








indicating chat the network 








subsystem is unusable. 


W S A VERNOT S U P PORTE D 




10092 


Returned by WSAStartup () 








indicating that the Window* Sockets 








0LL cannot support this app. 


WSANOTINITIAHSED 




10093 


Returned by any function except 








WSAJtajtup () indicating that a 








successful WtAJtftrtupO has not yet 








been 


aer formed. 


WSAhOST N0T_"0UND 


HOST_NOT_rOUND 


1L0OI 


As 


in 


BSD. 


WSATRY AGAIN 


TRY ACAIN 


11002 


As 


i n 


BSD 


WSANO RECOVERY 


NO RECOVERY 


1 1003 


As 


in 


BSD 


WSANO DATA 


NO OAT A 


1 1004 


As 


i n 


9S0 



The first set of definitions is present to resolve contentions between standard C error codes which may be 
defined inconsistently between various C compilers. 
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10 



The second set of definitions provides Windows Sockets versions of regular Berkeley Sockets error 

codes. 

The third set of definitions consists of extended Windows Sockets-specific error codes. 

The fourth set of errors are returned by Windows Sockets getXby YO and WSAAsyncCetXBy YO 
functions, and correspond to the errors which in Berkeley software would be returned in the h errrto 
, 5 variable. They correspond to various failures which may be returned by the Domain Name Service. If 

the Windows Sockets implementation does not use the DNS. it will use the most appropriate code. In 
general, a Windows Sockets application should interpret WSAHOST_NOT_FOUND and 
WSANO.DATA as indicating that the key (name, address, etc.) was not found., while 
WSATRY. AGAIN and WSANO_ RECOVERY suggest that the name service itself is non-operational. 

20 

The error numbers are derived from the winsockJi header file listed in section A.2.2. and are based on 
the fact that Windows Sockets error numbers are computed by adding 10000 to the "normal" Berkeley 
error number. 

25 Note that this table does not include all of the error codes defined in wiosock Ji. This is because it 

includes only errors which might reasonably be returned by a Windows Sockets implementation: 
winsockJi. on the other hand, includes a full set of BSD definitions to ensure compatibility with ported 
software. 

30 
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A.2 Header Flies 

A. 2.1 Berkeley Header Files 

A Windows Sockets supplier who provides a development kit to support the development of Windows 
io Sockets applications must supply a set of vestigial header files with names that match a number of the 

header files in the Berkeley software distribution. These files are provided for source code compatibility 
only, and each consists of three lines: 

Hfrvlef _WtNSQCKAPl_ 
* :nc!':da <winsock.h> 
75 tertdif 

The header files provided for compatibility are: 
netdb.o 
arpa/ineLh 
20 sys/time.h 
. sys/socketh 
oetinet/inJi 

2S The file winsock.h contains all of the type and structure definitions, constants, macros, and function 

prototypes used by the Windows Sockets specification. An application writer may choose to ignore the 
compatibility headers and include winsockJi in each source file. 
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10 



15 



3S 
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A.2.2 Windows Sockets Header File - wlnsock.h 

The wiosock.h header file includes a number of types and definitions from the standard Windows header 
file windows.li. The windows.b in the Windows 3.0 SDK (Software Developer's Kit) lacks a * include 
guard, so if you need to include windows^ as well as winsock.h. you should define the symbol 
.INC. WINDOWS before ^including wtnsock.b. as follows: 
^include <windows.h> 
#define _INC_WINDOWS 
#inciude <winsock.h> 
Users of the SDK for Windows 3.1 and later need not do this. 

A Windows Sockets DLL vendor MUST NOT make any modifications to this header file which could 
impact binary compatibility of Windows Sockets applications. The constant values, function parameters 
and return codes, and the Like must remain consistent across all Windows Sockets DLL vendors. 

20 wiNSOCK.H — doeinitions to bo used with the WtWSOCX.DLL 

• This header fiU corresponds Co version i.i of c * # window. SocKets specification. 

• This file includes parts which are Copyright <c> i932-l93« Regents 

• of Che University of California. All rights reserved. The 

• Berkeley Software License Agreement specifies the terms *nd 
oc * conditions for redistribution. 

•/ 

lifndef _WtNSOCKAPI_ 
I define ~WINSOCKAPI_ 

/ • 

• Pull in WINDOWS. H if necessary 
30 •/ 7 

•ifndef _rNC_HIN0OWS 
•include <wLndows.n> 
#endif /• _TNC WTN0OWS •/ 



•^3asic system type definitions, taicen from crxe BSD file sys/types.h. 

cypedef unsigned char u_char; 

cypedef unsigned short u_shorc; 

cypedef unsigned mt u int; 

cypedef unsigned long u~long; 

/• 

• The new type to be used in all 

• instances which refer co sockets. 
•/ 

cypedef u_inc SOCKET; 
/• 

• Select uses arrays of SOCKETS. These macros manipulate such ' 
4 c . !!f; y !\ « *>• defined by the user before including 
45 ' cnt * fli«. but the default here should be >. 64. 9 

I ?SX?™ fMPLEMENT0R * nfl US£ * : THESE MACROS AND TYPES MUST 3E 

• IJ4CU7DEO £N WINSOCK.H EXACTLY AS SHOWN HtkZ . 
•/ 

lifndef FD_SETS tZE 
• define FD~SETS ZZZ 64 
SO «endif /• FD_SETSC2E •/ 

typedef struct fd_set I 

u_snort fd_count; /. hC w many are SE*"» •/ 

SOCKET fd_array{FD_SETSlZE] ; /• * n array of SOCKETS '/ 
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> fd_set 

extern int PASCAL FAR WSAFD IsSet ( SOCKET. :d set FA* •) 
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10 



15 



20 



j _ : r. . i ; \ 

. for ( : » 0; i < * < ^_s°* "A? • > ( se: » » - > : dcour.c ; ;*-) • \ 

: : ( ( (!4_s9*. ?kZ • ) (s«:) ; - >J2_a::iyf if •- :r> \ 

v - : . i i ; < i (M_se: TAP • Msec i )- >fd -:ount > i \ 

( < f isei FAR ~> (set) >->?d_ array! I j » \ 

Hfdi^ "AS • > ( set > » -> fd_*rray i i - L : ; \ 

i * » ; \ 

I \ 

l (fd_set FA3 • > ( set I J -> Cd_rount -- ; \ 
oreak; \ 

I \ 

) \ 
) whUo<0) 

•define ro_SET<fd, jet) io ( \ 

if <(<fd_set FAR ' ) ( set ) > -> fd_coun: < FD_SETSIiE) \ 

<<fd_sec FAR • > (set) t -> fd_array E ( i fd^set FAJ* • Mset ) ) - > Cd_cour.t - * I -fd; \ 
I wmle(O) 

•define F0_2ERO(set) <<<fd_s«t "A3. • ) < s*t ) > -> f d_count -0 ) 
•define FD_tSSET(fd, set) wSAJ"D£sSet ( (SOCKET) fd, (fd_set "Aft Mset) 



* Structure used in selectO call, taken (ram the 950 file sys/time.h. 
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struct timeval 
long 
long 

) ; 



t v_sec; 
tv usee; 



seconds */ 

and microseconds 



Operations on timevals. 

NB: timer cmp cot) not work foe > • or <-- 

f 

•define t lmer isset { t vp) < ( t vp) -> tv_sec II < cvpj ->tv_useci 

•define t imercmp (tvp, uvp, cmp) \ 

( (tvp) ->cv_sec enp <uvp> -> tv_sec II \ 
(tvp) ->tv~*ee (uvp)->tv - a«c 44 ( tvp) ->t v_usec cmp < uvp) ->cv_usec) 
• define timerelearTtvp) iz vp) - >tv_sec - ( tvp7->tv_usec - 0 
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Commands Cor ioct 1 socket <) , 



taken from the 3SD file fcntl.h. 
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SO 



• toctl*s have the command encoded in Che lower word, 

• and the sue of any in or out parameters in the upper 

• word. The high 2 bits of the upper word are used 

• to encode the in/out status of the parameter; for now 

• w« restrict parameters to at most 129 byt«s . 



•define tOCPARM_MASK 
•define IOC VOID 
• define IOCJ3UT 
•define IQC~IM 
•define t0C*IN0UT 



0x1 t /* parameters must be < 129 bytes */ 

0*20000000 /* no parameters */ 

0x40000000 /* copy out parameters */ 

QxSQQOOOOO /• copy in parameters •/ 



•aefine _IQ<x,y) 

• define ^lORU, y, t) 

• aefine _I0W<x,y,c) 



Idefine Frot*READ 
•define FIONBIO 
•define FtOASYNC 



<I0C_tNl tOC_OUT) 

~ /* 0x20000000 distinguishes new 4 

old Loctl's •'/ 

( £OC_VO:0Ux<<8> ly) 

(IOC_OUTl ( ( (ionq)sneof ( t ) fc IOCPARM_MASK)<< 1 6> I lx<<3> ly) 

( I0C_ENI ( ( (long)sizeof <t ) 4 t0C?APM_KASK)<<l 6) I (x<<8) ly) 

_I0R(*f. 12?, u_lonq> /• qec • bytes to read •/ 
~ICW('f, L25, u_Lonq> /• set/clear non-blockinq i/o •/ 
~lGUt*i\ 125, u_lonq> /• sat/cleac async i /o •/ 
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/• Socket I/O Controls */ 

• rtefine STOCSHIWAT JCWCi', 
•define SIOCCHIWAT "lORt's' ( 

• define SIOCSLOWAT "lOWCs'. 



0, u_iong) /• set high watermark •/ 

1 , u_long> /• get high watermark •/ 

2, u_long) /• set low watermark V 
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SZZZZ'.Z'^r _:z?.i'i', I. jj.zr.^i /* ;<at low 



/5 



f:;' ; : tjr " r *' »y -•-.wor< dacj odi- library. : d ^n from ::.e 

" ; -e.ib.n. A : L dresses 4:9 supplied m host order, and 

r «a - - r r. 9 ^ .*«:'or< oczer (suitable for jse m system -rails). 



s: rue* hostent ( 

ehac FAS • h^da«; official nuie of host */ 

char "AS • FAR • haliases; /• Alias list •/ 

short h_addrtype; /• host address type •/ 

sr.ort n_Length; /• length of Address •/ 

-Mar TAR • FAR • h_addr Us:; /• list of addresses •/ 

• define h_addr h_addr_l 1st £ 0 1 " /• address, for backward compet 



• It is assumed here that a network number 

* fits ;n 32 bits . 



20 



struct necenc ( 

char FAR • n_.naae; 

char FAR • FAR • n_aliases; 

short n_addrt ype; ™ 

'j_ionq n_nec; 

1 ; . • 



/* official najn* of net 

/• aLias Use •/ 

/* net address type • / 

/• network » •/ 



2S 



struct servant [ 

char FAR • s_na.Te; 

char FAR * FAR • s_aliases; 

short s__port; 

char FAR • 5 proto; 

» , 



/• official service name •/ 

/• alias list •/ 

/• port f •/ 

/• protocol to use •/ 



30 



35 



/• official protocol name 
/• alias list •/ 
/• protocol • */ 



struct protoent { 

char FAR • p_name; 
char FAR • FAR • p_a liases; 
short p_proto; 

f ; 
/ • 

* Constants and structures defined by the internet system, 

• ?er RFC 790, September 1981, taken from the 9S0 file net mt: / in . h . 
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• Protocols 
•/ 

♦define IPPROTO IP 

•define IPPROTO^tCMP 

•define IPPROTO^CGP 

•define IPPROTOJTCP 

• ceft.ne IPPROTO~PUP 

•define IPPROTO~*UDP 

•define I?PROTO~IDP 

•define IPPROTOJ*D 

•de f 1 ne IPPROTO_RAW 
Idefir.e IPPROTO MAX 



0 

1 

2 

6 

12 

17 

22 



255 
256 



/ • dummy for IP • / 

/* control message protocol •/ 

/• gateways (deprecated) •/ 

/• tcp •/ 

t* pup •/ 

/• user datagram protocol •/ 
/* xni idp •/ 

/• UNOFFICIAL net disk proto •/ 



/* raw IP packet 



Port/socket numoers: network standard functions 



SO 
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•define t?PORT_ECHO 7 

•define C?PORT_0 ISCARO 9 

•define IPP0RT_S YSTAT it 

•define IPPORT DAYTIME :3 

•define CPPORT~t*E7STAT :$ 

• define CPPORT^FTP 2L 
•define IPPORTJTELNET 23 
•de f 1 ne : PP0RT_SM7P 2 5 

• defme IPPORT~T IMESERVER 37 
•define :PPORT_NAMESERVTR 4 2 
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«:<?:;ne Z??Z?.? "nam 
»:e::r.e I ??*:?. 7 MT? 



• Por:.':o::'.e*. ••■js-.s-ra: -oat specific f ';r.:: '.i.-.a 

fcefir.e :??C?T_T7T? * ) 

• •leftne C??0?.T~3JI - 

/o t<i« fine c?port"f:>k:=:r 

»a«eine :?pcrt~tt? l :nk si 

Idefine r??ORT~SUP0UP 95 



• r JNIX TCP sockets 

• / 

• def;ne :??OP,T_EXECSE?.VXR 5L2 
♦define IPPORT^LOGINSEP.VER 5 13 
•define I?PORT_CMDSERVta 5 14 

• define r?PORT EF SSERVER 520 



IS 



/ * 

• UNtX UOP sockets 
•/ 

^° #cefine IPPORT_B rFFUOP 512 

»dflfin« I p?ORT~WHO SERVER 513 

♦cefine r??ORT~ROUTESERV-R 520 



40 
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/• 520»i also used •/ 



/• 

* Ports < :?PORT_R£SERVIO are reserved for 
2$ * privileged procais«s (e.g. root). 

*/ 

»defm« IPPORT_RESERVTD 102« 
/• 

* Link. r,ustb«rs 
•/ 

•cerine IMPLINK_EP 155 
* J£) »d«fine IMPLI^~LOWEXP£R 15$ 

^define tMPLINK~H tGHEXPER L53 

/• 

* internet address (old style. . . should be updated) 
•/ 

« cruet in_Addr { 
35 union ( 

struct ( u_char s_b U s_b2, *„b3, s_b4 ; ) S_un_b, 
struct { u_ahort s_wi,s_w2; ) S_un_w ; ~" 
u_long S_addr; 
} S^un; ~ 
•define s_addr S_un.S_ addr 

/ • can be used for most ccp & ip code 

tdefme s_host S_un . 5_un_b . 3_b2 

~ /" host on xaip */ 
fdefme j_net S_un.S_un_b. s_bL 

~ - - - / . n#CwocJ ( ./ 

tdsfme s imp S un . S_ un_w. s_w2 

~ ~ " ~ /• imp */ 

tdefine s^impno S_un . S_un_b . s_b4 

""""/• imp t •/ 
45 tdefine »_lh S_un.S_ur_b.a_bJ 

~ * /• logical host •/ 

} ; 
/• 

* Definitions of bits in internet address integers. 

* un subnets, the decomposition of addresses to host and net parts 
' is done according to subnet mask* not the masks here. 

* / 

Idefine IN CLASSAU) (ULongMD 4 OxSOCOOOOO) 0) 

•define rw"CLASSA_WET OxffOOOOOO 
define CN*CLASSA_NSHirT 21 - 

Icefme IN~CLAS3a""H0ST 0«00ffCfff 
Idefine CN_CLAS3A_MAX 129 
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10 



1S 



•ce:': ~* 








f re 


IN_~1A3.S 3_N£7 


:x: : :c: 




< 








:' . n« 


:M~ClA33B^HOiT 






• •ie :*;.-.«» 








#d« ; ; r.e 


--A3JC ( . J 


< < 1 lor.g) f i > 


i jxc20;3300) 


»<ie : : ne 




Oxf f f fff30 




•de f i.-e 




3 




»def:,-.o 


:S_CLASSC_HOST 


OxOOOOOOf f 




•def tr.e 


:naodr_any 


<u long)3xC 


ococooo 


• do fine 


:maddr~loopsack 


Cx7f00000'. 




'do fine 


:nador~9ROadcast 


(u LongjOxf 


ittittt 


tde f me 


::jaddr~none 


Oxf f f fffff 





:x3o:c;c >:» 



oxc-:ccoooq» 



* Socket address, 



Lncecrte;: stvle. 
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struct sockaddr_m ( 

short s in_ family; 

struct in_addc sm_addr; 
c.idr sin_ieco(31 ; 

} ; 



♦define WSAD£SCRIPTION_ T .EN 
•define WSASlfS STATUS L£N 



236 
129 
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eypecef struct WSAOata I 
WORD 
WORD 
char 
char 

unsigned short 
unsigned short 
char TAR • 
} WSAOATA; 

typedef WSAOATA FAR * LPWSAOATA; 



wVecs ion; 
wHighVersion; 

azDescnpc ion( WSADE3CRCPTI0N LEN*1| ; 
szSystenSt at us ( WSASYS_STATUS~LEN* 1 1 ; 
lMa,xSockets; ~ "~ 

iMaxUdpCg; 
IpVendor I n Co; 
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Options for use with [gs J etsoekopt at the IP level. 



♦define I? OPTIONS 



/• set/get CP per -packet options •/ 



■ Definitions related to sockets: types, address families, options, 
* taken from the BSD file sys/socket . h . 



40 



This is used instead of -1, 
SOCKET type is unsigned. 



since the 



•define INVALID SOCKET 
f define SOCKET ERROR 



(SOCKET) (-0) 
(-U 



45 



m Types 
•/ 

•define SOCK STREAM 
tdefme SOCK_0CRAM 
•define SOCK~RAW 
•define SOCKJIOM 
t define SOCXSEQPACKET 



/• stream socket •/ 

/• datagram socket •/ 

/* raw-protocol interface •/ 

/• reliably-delivered message */ 

/• seg,u«nced packet scream •/ 



SO 



• Option flags per-sockec. 
•/ 

•define SO_3ES0C 0x0001 

•define SO~ACCEPTCOyN 0x0002 

tdefine SO_R£USEA0DR 0x0004 

•define SO_K£EPALIVE 0x0008 

•define SO~0CWTROUTE 0x0010 



/* turn on debugging mCo recording 

** socket has had listeno ♦/ 

/• allow local address reuse •/ 

/* keep connections alive */ 

/• just use incecface addresses '/ 
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• ief-. 3c_5?."aeca3t :.<::!') 

• sefme jo_^c9:n"_:s£ :xol:-o 

ice :'i.-e 5: 3" NT 1 1 



s^r.cir.a of oro*d:js* .ts-ts 
=ypa*s Ki:;w4r* possible */ 

::r.T»r o.i zioso if dd'.i prescr.c * 



JO 
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• Additional options. 
•/ 

•define so_SNoeor o * l o ■: i 

• defi.-.e S0~?.CV8Ur CxlOG2 

•define SO~3M0LOWAT OiclOCJ 

•define 50 SCVLOWAT 0xlGC4 

» go line S0~SS0T:M£O 0xL00 5 

lde:i!ift SO RCVTIMEO 3x100 6 

•define SO^S^ROR OxlOOT 

•defir.e SQ~7Y?E 0x1009 



send Suffer 3i:a */ 
receive out far sua "/ 
send low-water mark •/ 
receive loy-wat«r .D«r)( */ 
send c imeout • / 
receive :i.ti«ou; */ 
•;et error status and clear 
qet socket type •/ 
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/ * 

• ?C? opt tons . 
•/ 

•define TCP NOCELAY 



25 



30 
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* Actress 
•/ 

•define AT 

• define Ai* 
•define AT " 
Idadno AT 
♦define A"* 
•define Ac] 
•define AF. 

• define Ar" 
•define fis\ 
♦define AF* 
•define PS[ 
•define AT* 
•define AS\ 
♦define AT 
•define AT] 
tdefine AF] 

• define AT* 

• define at] 

• define AT* 



f ami lies . 

(JNS?££ 
UNIX 
"iNET 
TMPLIMK 
PUP 
CHAOS 

'us 

'iSO 

osr 

ECMA 
DATAKIT 
CCITT 
SNA 

OECnet 

"ol: 

LAT 

'appletalk 
'netb:os 



AT _I33 

a 

9 

10 
IL 
12 
13 
14 
IS 
I 6 
17 



/■ unspecified */ 

/* local to host (pipes, portals) */ 
/" internetwork: UDP, TCP, etc. */ 
/* arpanet imp addresses •/ 
/* pup protocols: e.g. 8SP •/ 
/• .lit CHAOS protocols */ 
/* XEROX MS protocols •/ 
/• ISO protocols •/ 
/• osi is rso •/ 

/■ ouropean computer manufacturers */ 

/'• datakit protocols •/ 

/• CCITT protocols, X.25 etc •/ 

/• I3M SNA V 

/• DECnet •/ 

/• Direct data link interface */ 
/• 1AT •/ 

/• NSC Hyperchannel •/ 

/• AppleTalk •/ 

/■ NetBios-style addresses •/ 



• define A.- MAX 
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Structure used by Kernel co store most 
addresses . 



struct sockaddr f 

u^short sa_family; 
char sa_data(l4l; 

\ ; 



address family */ 

op to 14 bytes of direct address 
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• Structure used by kernel to pass protocol 

* information in raw sockets - 



struct sockproto ( 

u_shoct sp_fanily; 
u short sp^protocol; 

) i 



address family 
protocol •/ 



SO 
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Protocol families, same as address families for now. 



•/ 

•define PF_ONSP£C 
•define PF UNIX 
•define PF~IMET 
• define PF tMPLIWTC 
•define PF POP 



AF_UNSPEC 
AT UNIX 

ATirxrr 

AT _ IMP L I tfK 

AT PUP 
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w 



15 



20 



35 



45 





?" "HAGS 


^ r CHAOS 


-e 


?F~N3* 


A F ~ N S 




?r 


AF~t30 


• iof :r.« 


?r os: 


AT OS I 


l ie ::.-<* 


?F 11 MA 


AF~FXMA 


•def:r* 


?-~2atax:7 


af'satax:? 






af~cc:?t 


•cef ir.e 


?F~3SA 


af'sna 


taof 


PF GECnet 


AF~3ECnet 


• cefir.e 


pf'ol: 


af'olc 


#def l -e 


PF LAT 


Ar *LAT 


•define 


pf_hyl;:ik 


AF H If L INK 


•cefi.-.o 


P F_ A? P LE7ALX 


AF ~AFP LSTALK 


• de f me 


?F_MAX 


AF_ttAX 









* Structure used for manipulating ii.iger option. 
•/ 

s:cjc: linger \ 

u.short l_onoff; /• option on/off •/ 

u_short l^lmqer; /* linqar tim« •/ 

> ; 
/• 

* Level number for (get/set) sockopc ( ) to apply to socket itself. 
*/ 

•define SOL_30CK£T Oxffff /• options for socket level •/ 

/* 

2* * Maximum queue length specifiable by listen. 

•/ 

•define SOMAXCOMN 5 

•define HSG_0OB Oxl /• process out-of-band data */ 

•define MSC — PEEK 0x2 /♦ peek az incoming nwssage •/ 

•define MSG_DOMTROU*TE 0x4 /• send without using routing tables 



30* tdefine MSG_MAX tOVLEN 

/ • 
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•^Define constant based on rfc883. used by gethost byxxxx () calls. 
• define KAXGETHOSTSTRUCT 1.024 



• Define flags to be used with the WSAAsyncSelect ( > call. 
•/ 

•define FD^ READ 0x01 

•define F0~WR£TE 0x02 

•define FD~OOB 0x04 

•define FD_ACCEPT 0«08 

• define F0_COMNECT 0x10 

40 »defme FD_CLOSE 0x20 

/* 

" AH Windows Sockets error constants are biased by WSABASEERR fro.-n 

• the •notwal* 
*/ 

•define WSABASEERR 10000 
/ • 



♦^Windows Sockets definitions of regular Microsoft C error constants 



• define WSAXINTft (WSABASEERA* 4 > 
•define WSAXBA0F (WSABASEERR* 9 > 

I »defme WSAEACCES (WSABASEERR* L 3 > 

• define WSAEFAULT (WSABASEERJU 1 4 >" 
•define WSAEINVAL <WSA8ASE£RR*22> 

50 'define WSAEMFILE (WSABASEERJW4 ) 

/ • 

* windows Sockets definitions of regular Berkeley error constants 
•/ 

• define WSAEWOUL0BLOCK ( WS ABASEE?J*0 5 ) 

• d«fin» WSAEINPROCR£S5 (HSABA5CERR*3 6 ) 
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20 



25 



W3 A £M07 
»-qf:r.« W5A£2£3TADCa?.£; 
» =e.' ;.-.e WSAEMSCSCZE 
i-s WSA£ PROTOTYPE 

• WjA£N-;?R;TCC?T 

• a * : i r. e w J AE ? ?.C7 2 SO 3 *J ? ? •: P. T 
i:«f'.-a WSA£5."3CX?rJ03uP?C?.T 

• cor ir.e wiA£0?N0?3t;pp 

• vlefine WSAEPTNOiUPPORT 

• cefme WSAEAFNOSUPPOP.T 

• cefir.e WSAEACORIWSE 
fcodr.e WSAEADORNOTAVAIL 
•define WSAENETOOWN 

• dafir.e WSAENETUNREACH 
^afir.e WSAEHETRESET 
•define WSAECONNABORTSD 
•define WSAEC0SNRESE7 
•define wSAXMOBUrS 
•define WSAEISCONN 

• define WSAENOTCONN 
»d«Cin« W3AESHUT0OWM 
•define WSAXTOOMANYREFS 
•define WSAETIMEOOUT 
♦define WSA£CONNREFUSEO 
•define WSAELOOP 
•define WSAENAMETOOLONG 
•define WSAEHOSTDOWN 
•define WSAEHQSTUNREACH 
•define WSAENOTEMPTY 
•define WSAEPROCLIM 
•define WSAEUSERS 
•define WSAEOOUOT 
•define WSA£ STALE 
•define WSAZREMOTE 



(WSA9AS££?.? - J 7 > 
( W3ASAS ££?.?.- 13 ) 
( WS A 3A3 ££?_?.- 3 9 > 
(WSA3AS££?? *40 > 
CWSA5A5tt?.?. --4 1 ) 
( W3A3 AS ££?.." -4 2 > 
(W3AeA3£t??-i3> 
(WSA9ASE £??.-- 4 } 
<WSA£ASEE?.?.-4 5) 
(WSABAS££?.?.-4 6) 
(WSABASEERR-4?) 
<WSABASEERR*49> 
( WSABAS££RR*4 9) 
<WSA8ASEERR*50) 
(WSABASEERR*5l> 
(WSABASEERR*32) 
t WSABASEERROJ ) 
t WS ABASEERR ♦ 5 4 ) 
(WSABASEERR + 55 ) 
(WSABASEERR*56> 
(WSABASEERR+5 7) 
( WS ABASEERR* 58 > 
< WSA9ASEERR*39> 
{ WS ABASEERR* 60 ) 
<WSABASEERR*6l ) 
4WSABA5££RP.*62) 
<WSABASEERR*63) 
( WSA8ASEERR + 64 ) 
<WSABASEERR*65> 
(WSA8AS££RR*66> 
<WSABAS£ERR*S7> 
<WSABAS££RR»68> 
(WSABASEERR*69) 
<WSABASEERR*70> 
(WSABASEERROl) 
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' Extended Windows Sockets error constant definitions 



•define WSASYSNOT READY 
•define WSAVERNOTSUPPORTZa 
•define HSANOTINIT IAL I3ED 



{WSABASEERR*9i) 
< WSABASEERR* 92 ) 
{ WSA8ASEERR+9 J ) 
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Error return codes from gethostbyname ( ) and gethostbyaddr < ) 
(when using the revolver) . Note that these errors are 
retrieved via WSACetLastError ( ) end must therefore follow 
Che rules for avoiding clashes with error numbers from 
specific implementations or language run-time systems. 
For this reason the codes are baaed at WSABASEERR+1001 - 
Note also that ( WSA] N0_ADDR£5S is defined only for 
compatibility purposes. 



•define h ecrno 



WSACetLastError « ) 



/• Authoritative Answer: Host not found */ 

• define WSA*OST_NOT_r0UN0 < WSABA5EERR* LOO I ) 

•define HOST _ NOT FOUND WSAKOST NOT FOUND 
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/• Mon-Authontative : Host not found, or SERVtRTAIL •/ 
•define WSATRY ACAIN ( W5A BASE ERR* 1002 ) 

•define TRY ACALN WSATRY ACAtN 



/• Mon recoverable errors, 
•define WSANO_R£COVZRY 
•define NO RECOVERY 



F0RKZRR, REFUSEO, NOT I MP •/ 
(WSAaASEERA-1003) 
WSANO RECOVERY . 
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>' " V^lid nan*, no data record of requested type "/ 
•define WSANO DATA ( WSABASEERR* 1004 » 

•define NO 0ATA USANO 0ATA 
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/•no address, look for MX 
•define WSANO_AD0RESS 
•define MO ADDRESS 



record •/ 

WSANO^DATA 
WSANO~A00R£SS 
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w.-sdws Socicets errors refined as r^uUr 3, : y,u y * cror coaBtlfl:s 
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♦He;:.-.* iWOL*-3 3LOCK 

•define £ :\? scores 3 

»co fire EAIP.EAQY 
»def:.-.a EVCTSOCK 
•def;-e EDESTAOORREQ 
•define EMSCSTZE 
Mftfma E PROTOTYPE 
•define EN0PR0T0OPT 
•define EPROTONOSUPPO.RT 
•define ESOCKTMOSUPP03T 
•defxne E0PN07SUPP 
•define EPFNOSUPPCRT 
•define EAFNOSUPP0RT 
•define EADDRTNUSE 

• do fine EA0ORNOTA VA r I 
•define ENETDOWN 
•define £NETUMR£ACH 
•define ENETRESET 

• define SCOWABORTEO 
•define £CONNR£SET 
•define ENOBUFS 
•define ETSCOlfN 
•define ENOTCONN 
•define ESHUTDOWN 
•define ETOOMANYREf S 
•define ETIMEDOUT 
•define ECOWREFUSED 
•define ELOOP 

• define E NAME TOO LONC 
•define EHO5T0OWM 
•define EHOSTUNRXACH 
•define ENCTEMPTT 
•define EPROCL IM 

• da fine EUSERS 
•define EOOUOT 
•define ESTALE 
•define E REMOTE 

/* Socket function prototypes •/ 



W5AEH0UL39LOCK 
WSAEiNPRCGRESS 
W3AEALREACY 
W5 A E SOT SOCX 
WSAE0E5TADCAREQ 
WSAEMSGSCSE 
W3AE PROTOTYPE 
KSAENCPROTOOPT 
WSAEPROTOMOSUPPCRT 
WSAESOCK7N0SUPP0RT 
W3AZ0PNOTSUPP 
WSAEPFNOSUPPORT 
W3AEAFNOSUPP0RT 
WSAZAOORINUSE 
W3AEAD0RNOTAVA I L 
WSAENETOOWN 
WSAENETUNREACH 
WSA£NETR£SET 
WSAECONMA SORTED 
WSAZCONNRESET 

wsAENoaurs 

WSA£ISCONN 
WSAENOTCOKN 
WSA£S HUT DOW 
WSA£TOOMANYft£FS 
WSAETIMEOOUT 
WS A£ CO NNREFU5 E 0 
WSAELOOP 
WSAENAMETOOLONC 
WSAE.HOSTDOWN 
WSAEHOSTONREACH 
WSAENOTEMPTY 
WSAXPROCLIM 
WSA£USERS 
WSAEDOXJOT 
WSAESTALE 
WSA£ REMOTE 



•ifdef cplusplua 

extern *C" ( 
•endif 

SOCKET PASCAL FAR accept (SOCKET s, struct sockaddr FAR -addr, 

mc FAR ♦aaarlen) ; 

I int PASCAL FAR > lM (SOCKET con.t «r«t ,o=*.ddr FAR - Mde . lne „ Ml-)( 

int PASCAL FAR closesocket (SOCKET *>; 
I int PASCAL FA* connect (SOCKET con.t struct .ocluOdr FAR -name, int na^elen,, 
int PASCAL FA* io« laocket (SOCKET long cmd, u_lo„g FAR «argp> ; 

int PASCAL FAR g«peern*me ( SOCKET s. struct tockaddr FAR -na*., 

int FAR * namelen) ; 

int PASCAL FAR gecsocXname (S OCX£T s, struct sockaddr FAR -najne, 

int FAR * nanelen); 

inc PASCAL FAR getaockopc <SOCK£T s. int lavel. .mc optname, 

cr.ar FAR • optvji, mt FAR *optLan); 
•j_long PASCAL FAR htonl <u_long hostlsng); 
u_short PASCAL FAR htons <u_snort hostshort); 
I unsigned long PASCAL FAR mec_addr (const char FAR • cp) ; . 
char FAR * PASCAL FAR met.ntoa struct in.addr in); 
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? - i t A L "A?. L : s 9 n i 2 ZZ'/Z~ s . nc saclcLcj); 
PASCAL "AS -:oal ( j_Iop.cj n«tlong>; 
- ^ r. ; r ?A .3 CA 1 "A?, r.-or.s ( j_shorc .".*»r. shar; i ; 

: r. PASCAL FA?. re:v (Sr^KIT s, ~har FAR • b'jf, ir.: ler., fls.;.;); 

in*. PASCAL FAR recvfrom < SOCKET s, char FAR • auf, wc l*n, tnt flags, 

struct soc<aadr FAR •from, ; nt FAR • fron.em; 

in- PASCAL FAB seLect <:n: nfds, fd_set FAR *r»adfds, fd_s*t FAR 'wrirefds, 

fj_set F Ail 'except fds, cons: struct :i.-n«vil FAS 'timeout); 

15 | :n: PASCAL FAR send {SOCKET s, const char FAR * buf. int Len, int flags); 

|:nc PASCAL FAR s*nc:o (SOCKET s, const chir FAR • but, int Len, int flags, 
const struct sockacdr FAR 'to, int tolen); 

me PASCAL FAR setsockopt (SOCKET s, trie level, inc opt name, 
|* const cnar FAR • optval, ;a: optlen); 

20 int PASCAL FAR shutdown (SOCKET s, inc ho«> ; 

SOCKET PASCAL FAR sock«; (tnt af, tnt type, int protocol), - 

/• Database function prototypes •/ 

| struct hostenc TAR • PASCAL FAR gethost byaddr < const char FAR * addr. 
2S mt Len, int. type); 

( struct hos'.ent FAR " PASCAL FAR ?ethostbynajne (const char FAR * najn«) ; 

| in: PASCAL FAR gethos cnaiM (char FAR • name, ir,i namelen); 

| struct servant FAR ♦ PASCAL FAR get s« rvbyport ( tat poet, const, char FAR • proco); 

'30 I struct s«rv«nt FAR * PASCAL FAR, got servbynajne (const char FAR • nam*. 

I const cnar FAR * proto>; 

struct protcenc FAR * PASCAL FAR qatprocobynuAMcUnt proto) ; 
| struct protoent FAR • PASCAL FAR get protooyname (const char FAR * name); 
35 /• Microsoft Windows Extension function prototypes •/ 

int PASCAL FAR. WSAStart up (WORD wV«rsionRequired, LPWSAOATA LpWSAOata) ; 

int PASCAL FAR WSACleanup ( void) ; 

void PASCAL FAR wSASetLastError ( int lError); 
40 mt PASCAL FAR WSAGetLa st Error (void) ; 

BOOL PASCAL FAR WSAI sBlockmg (vo id i ; 

int PASCAL FAR WSAUnhookBlock mgHook ( void) ; 

FAR? ROC PASCAL FAR WSASet BlockinqHpok (FARPROC IpBiockFunc > ; 
int PASCAL FAR WSACa nee 1 3 lock ingCa I t t vo id) ; 



HANOLC PASCAL FAR WSAAsyncCet ServByName (HWNO hWnd, u_tn: wMsg, 

const char FAR * naine, 
const char FAR » proco, 
char. FAR • :>uf, tnt buflen); 



50 HANDLE PASCAL FAR WSAAsyneCetServ3yPort (HWND hWnd. u_i nt wft»q, ir.t port, 

I censt char FAR • proto, char FAR * buf, 

in: button); 

HANDLE PASCAL FAR WS.AAsyncC*tProro8yName IHWNO hWnd, u_int wMscj, 
I const Char FAR • najne, char FAR ■ buf, 

i. -:t but I an) ; 
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;.it -cnber, 3hir FAS • a.;:, 
int buf lenj ; 

~^::ZlZ ? AJCAl ~A?. wJAAs/-;Ce:Kosi3yNa:ne (KWND l\Wnd, *j_;n- v.ysg, 

csr.si char "Aft * .-.dff-e, cnar FAR * buf,- 
tnt buf Ian) ; 

HA NO L£ ? AiCAL FAR Wj AAs y r. cCet Host ByAdd r ( HWND r.Wnd, u_i.u -Msg, 

cons; char TAP • *<acr, in - l* n , mt tvoe, 

const char FAil • ouf, :nt oufler.); 

ins ?A3CAL "AS W3ACar,-e LAs yncRequest t HANDLE hAsyncTaskHandle) ; 

75 in - ? A ^CAL TAR WSAAsyr.cS«lect (SOCKET 3* HWNO hWnd. u^lhc wHsq, 

long iEvenci; ~* 

i»i!def cpLusplus 
) 

/• Microsoft window* Extended data types "/ 
20 typedef sccucc socKaddr S0CKA00R; 

typedef itrucc soefcaddr *PSOCKADDR; 
typedef struct sockadcr FAB 'LPSOCXAODR; 

typecef acruc: sockaddr in SOCKAOOR [tf; 
typadaf struct sockaddr'in •?SOCKA00R_tN; 
typadaf icruc: sockaddr_in FAft •LPSOCttAOOR IH; 

cypeder Struct linger LINGER; 
typecef struct linear 'PLINCER; 
typedef struct linger FAR * L? LINGER ; 

typedef struct in_addr iy ADDR; 
typedef struct i.-i_addr *?IN AODR; 
typedef struct 1 n~a ddr FAR ~L?IN_ADDR; 

typedef struct fd_set rO_SET; 
typedef struct fd'set *PF0_SET; 
typedef struct fd'sec FAR • L?FD_SET ; 

typedef struct hostant HOSTENT; 
typadef struct hostant ♦PHOSTENT; 
typadaf struct hoscent FAR •LPHOSTENT; 

typadaf struct servant SERVANT ; 
typadaf struct servant *PSERVENT; 
typedef struct servant FAA * LP SERVE NT; 

typedef struct protoent P R OTOE NT; 
typedef struct protoent 'PPROTOENT; 
40 typedef struct protoent FAR • LP PROTOENT; 

I typadaf struct tiaeval TIMZVAL; 
typadaf struct timev«i *PTEMEVAL; 
typedef struct timeval FAR -LPTIMEVAL; 

/* 

Windows massage parameter :ompontion and decomposition 
45 * macros. 

* • «SA*AXEASYNCR£PLY is intended for use by the w in do-s Sockets impl.mentat ion 
I ^ uh «« constructing the rasponsa co a w S AAsyncCatX3y Y 1 ) routine. 

•define WSArtAJtEAS YNCR£?IY (buf len. error) MAAZLONG (bu < lan, error > 

SO I ! wha^ A cin«-^ PLt ,i S lnt * Rded Cor u " b * th « "meows Sockets implementation 

I , y constructing the response to WSAAsyneSelect ( > . 

•define WSAMAKESELECTRZPLY (event* error) MAiCELGNC (event , arron 



wSAGETASYNCaUFLEN is intended for use by- the Windows Sockets appii^ciDn 
to extract the buffer length from the LPara/n m the response 



55 



BNSOOClD <EP 07709S8A1 I > 



136 



EP 0 770 958 A1 



wlnsock.h 124 



5 * to a WSACetX3yY < > . 

»lef:r,e W3 ACETA5 YNC3UFLIN ( 1? aram > ^IWCRD{ LParam) 
/ • 

• W3ACZTA5 YNCERRCR is intended for use by the Windows Sockets Application 

• to extract t ne error ;ode J com the 1 Pa ram : r. the response 

• to « WSAC*tX3yY ( ) . 
70 •/ 

ide fine WSACETA3 YNCERROR ( IParam) H : WORD (IParam) 

• WSAGETSELECTEVENT is intended for use by the Windows Sockets application 

• to extract the event code from the IParam tn the response 
- to a wsAAayncSelect < ) . 

•/ 

15 Idefine WSAGETSELECTEVENT ( IParam) LOWORD ( LParam) 

/ • 

• WSACETSELECTERROR is intended for use by the Windows Sockets application 

• to extract the error code from the IParam in the response 

• to a WSAAsyncSelect ( ) . 
•/ 

20 Idafme WSACETSELECTERROR < 1 Pa ram ) H I WORD ( LPa ram) 

lendif /• WINSOCKAPI •/ 
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Appendix B. Nlot f ? f o r Windows Sock^s Suppliers 
B.1 Introduction 

A Windows Sockets implementation must implement ALL the functionality described in the Windows 
Sockets documentation. Validation of compliance is discussed in section B.8. 

I Windows Sockets Version 1.1 implementations must support both TCP and UDP type sockets An 
implementation may support raw sockets (of type SOCK.RAW). but their use is deprecated. 

Certain APIs documented above have special notes for Windows Sockets implemeniors A Windows 
Sockets implementation should pay special attention to conforming to the API as documented The 
Special Notes are provided for assistance and clarification. 

B.2 Windows Sockets Components 
B.2.1 Development Components 

^STk ^^"T 161 " MmpC ° £B1S {<x ^ b * Wu3d °^ Sockets application developers will 
be prov,ded by each Wtndows Sockets supplier. These Windows Sockets development component TareT 

Cnmnnnfnt rv^nrt™ 

Windows Sockets Documentation This document 

WTNSOCKIJB file Windows Sockets API Import Library 

WTNSOCX.H file Windows Sockets Header File 

NETDB.H ^ Berkeley Compatible Header File 

ARPAANET.H file Berkeley Comparible Header File 

SYS/TIME Ji file Berkeley Compatible Header File 

SYS/SOCKET.H file Berkeley Compatible Header File 

NETINEr/IN.H file Berkeley Compatible Header File 

B.2.2 Run Time Components 

The run time component provided by each Windows Sockets supplier is. 
Ca a nrmrn t . Descripnnq 

W1NSOCKDLL The Windows Sockets API implementation DLL 

B.3 Multlthreadedness and blocking routines. 

Data areas returned by. for example, the getXby Y0 routines MUST be on a per thread basis. 

rT. t rt," n a W»ic«ion MUST be prevented from making multiple nested Windows Sockets function 
caUs. Only one outstanding function call will be allowed for a particular task. Any Window, Sockets 
W JESS^^*" ZT* bUKkiB * " outsunding will fail with an error code of 

WAhBTu- a J^ rc tW0e ««P 0 <« «> tnis restriction; WSACat^lockingCallO and 
5?* Wmdow, Socket, suppliers should nc^although 

prehnuaary drafts of this speculation indicated that the restriction only applied to blocking function 
aSis".^^ t*"™**** to — -n-blockingcalls while". Socking ca^^ss. 

^garding the implementation of blocking routines, the solution in Windows Sockets is to simulate the 
blocking mechanism by having each routine call PeekMcssageO « it waits for the completion of its 
operation. In anncipanon of this, the function WSASetBlcckingHookO is provided to allow the 
programme/ to define a special routine to be called instead of the default PeekMessageO loop The 
blocking hook functions are discussed in more detail in 4.3. 13. WSASetBlockingHookO 
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B.4 Database Files 

The database routines in the getXby Y() family (getbostbyaddrO. etc.) were originally designed (in the 
first Berkeley UNIX releases) as mechanisms for looking up information in text databases. A Windows 
Sockets supplier may choose to employ local files OR a name service to provide some or all of this 
infonnatioa. If local files exist, the format of the files must be identical to that used in BSD UNIX, 
allowing for the differences in text file formats. 



B.5 FDJSSET 

75 n is accessary to implement the FD_ISSET Berkeley macro using a supporting function: 

WSAFDIsSetO- It is the responsibility of a Windows Sockets implementation to make this available 

as part of the Windows Sockets API. Unlike the other functions exported by a Windows Sockets DLL. 
however, this function is not intended to be invoked direcdy by Windows Sockets applications: it should 
be used only to support the FD.ISSET macro. The source code for this function is listed below: 



20 
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int FAR 

WSAFDIsSet (SOCKET fd, fd_set FAR *3et) 

( 

inc i - set->f d_count ; 

while (i — > 

if (sec->f!cl_array [i ] ~ fd) 
return 1; 

return 0; 

) 



B.6 Error Codes 

In order to avoid conflict between various compiler environments Windows Sockets implementations 
MUST return the error codes listed in the API specification, using the manifest constants beginning with 
"WSA". The Berkeley-compatible error code defmiaons are provided solely for compatibility purposes 
for applications which axe being ported from other puuforms. 



B.7 DLL Ordinal Numbers 

The winsock.def file for use by every Windows Sockets implementation is as follows. Ordinal values 
starting at 1000 are reserved for Windows Sockets implementors to use for exporting private interfaces to 
their DLLs. A Windows Sockets implementation must not use any ordinals 999 and below except for 
those APIs listed below. An application which wishes to work with any Windows Sockets DLL must use 
only those routines listed below; using a private export makrv an application dependent on a particular 
Windows Sockets implementation. 



45 ; Fil«: winsock.def 

; System: MS-Windows 3.x 

; Summary: Module definition file for 'Windows Sockets OIL. 
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LIBRARY WCNSOCK ; Application's module mm* 

DESCRIPTION ' BS0 Soclcoc AJ> I tot Windows' 

EXETTPE WINDOWS , required for all windows applications 

STUB • w:>fST*Ja. ZXZ ' .. ; generates tr:or message if application 

; is run witnout windows 

;C00E can be FIXE0 in memory because of potential upcalls 
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- - . .• .XiD s r srr : r 



H£A?3:2» 



10H 



10 



15 



20 



25 



30' 



; Ai: '.jr.ccior.s char. 0 9 called oy any Windows ro-Jtin* 

; »us: e« axpor.ed. a.-.v iflsi::or.j; «xpor-.j beyona -hose define 

; here mus: hav« orr.ra; rvjmoers 1003 or <oov«. 

EXPORTS 
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ACCQpC 


9 I 


bi nd 


32 


closesockec 


93 


co o nocc 


94 


gatp«ocnajne 


95 


getsockname 


*6 


gecaockopt 


?7 


htonl 


38 


hconj 


39 


inet_addr 


310 


inet_ncoa 


911 


loccliocket 


912 


listen 


313 


ntohl 


314 


ntohs 


315 


recv 


316 


rocvf com 


317 


s*l«ct 


313 


sond 


313 


s«ndco 


920 


sacaockopt 




shutdown 


322 


socket 


323 


gethoscbyaddr 


351 


g*thoscbyn4LTi« 


352 


gatprotobyna/no 


953 


g*eprotobynumb*r 


354 


g*CsarvbynAme 


355 


g«ts«rvbypoct 


956 


g«tho3Cn*n>» 


957 


WSAAsyncSalact 


9101 


WS AAs y ncCecHosc 3yAddr 


3L02 


wSAAjyncC«cHoac9yN*m« 


9103 


WSAAsyncG*;tProtoByNunib«r 


9104 


WSAA»yncC«cProcoByN*ft« 


9105 


wSAA»yncC#cS«rv8yPorc 


9106 


WS AA s y n cC* c S • rv B y Nam* 


9107 


WSACancalAsyncRaquast 


9103 


WSA5«c Blockx ngtiook 


9109 


WSAUnhookB locking/Hook 


8110 


ws AG«x La sc Error 


9111 


wSA5«cLa«tError 


9112 


WSACancalBLockxngCall 


9113 


WSAtaBlockinq 


9114 


wSAStarcup 


9115 


WSACl«anup 


9) Lie 


WSATOIsSec 


9151 


W£p 


9500 



RES ICEHTNAME 



,eof 



£5 



B.8 Validation Suite 

^*?n?r SOt ? U API Tes *< WSAT) to ensure Windows Sockets compatibility between Window, 
Sockets DLL implementations * currently in beta test This beta version includes functionality testing of 
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the Windows Sockets interface and is supported by a comprehensive scripting language. The final version 
of WSAT will be available in Spring 1993. If you wish to receive the tester or more information on the 
beta, send email to wsat@microsoft.com. 
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Appendix C. For Furt her Reference 

This specification is intended to cover the Windows Sockets interface to TCP/IP in detail. Many details 
20 of TCP/IP and Windows, however, axe intentionally omitted in the interest of brevity, and this 

specification often assumes background knowledge of these topics. For more information, the following 
references may be helpful: 
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30 
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40 



Braden. R.[1989], RFC 1122. Requirements for Internet Hosts-Communication Layers. Internet 
Engineering Task Force. 

Comer, D. [1991], Internetworking with TCP/ IP Volume I: Principles. Protocols, and Architecture, 
Prentice Hall. Englewood Cliffs. New Jersey. 

Comer. D. and Stevens. D. [1991]. Internetworking with TCPUP Volume II: Design, implementation, and 
Internals. Prentice Hall. Englewood Cliffs, New Jersey. 
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Appendix P. Background Information 
0.1 Legal Status of Windows Sockets 

The copyright for the Windows Sockets specification is owned by the specification authors listed on the 
tide page. Permission is granted to redistribute this specification in any form, provided that the contents 
of the specification are not modified. Windows Sockets implementors are encouraged to include this 
specification with their product documentation. 

The Windows Sockets logo on the title page of this document is meant for use on both Windows Sockets 
implementations and for applications that use the Windows Sockets interface. Use of the logo is 
encouraged on packaging, documentation, collateral, and advertising. The logo is 
available on microdyne.com in pub/winsock as winsock.bmp. The suggested color for the logo's tide bar 
is blue, the electrical socket grey, and the text and outline black. 



D.2 The Story Behind the Windows Sockets Icon 

(by Alistair Banks. Microsoft Corporation) 

We thought we d do a "Wind Sock" at one stage-but you cry to get that into 32x32 bits! It would have had 
to look wavy and colorful, and... well, it just didn't work. Also, our graphics designers have "opinions'* 
about the icons truly representing what they are-people would have thought this was The colorful wavy 
tube specification 1.0!" 

I tried to explain "API" Trognsmming Interface" to the artist-we ended up with toolbox icons with little 
flying windows 

Then we came to realise that we should be going after the shortened form of the name, rather the in 
full... Windows Sockets... And so we went for that - so she drew (now remember Tm Fngi'ch nr )( j you're 
probably American) "Windows Spanner". aJca. a socket wrench. In the U.S. you'd have been talking 
about the "Windows Socket spec" OK. but in England that would have been translated as "Windows 
Spanner Spec 1.0** - so we went to Electrical sockets - well the first ones came out looking like "Windows 
Pignose Spec 1.0"!!!! 

So how do you use 32x32. get an international electrical socket! You take the square type (American & 
English OK. Europe & Australia are too rounded)-*you choose the American one. because it's on the wall 
in front of you (and it s more compact (but less safe. IMHO) and then you urn it upside down, thereby 
compromising its nationality! ~ 
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[IMHO = "In My Humbk Opinion"-*!.] 
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XtAppAddlnput \ xlev.™ 

Name 

XtAppAddlnput — register a new file as an input source for a given application. 
Synopsis 

Xtlnpucld Xc AppAdd Tnpuc <dpp_concexc . source, condizion, pcoc, clienz_daz*) 
Xt AppContext app_conzexz : 
Lnc source; 
XcPoincer condic ion; 
Xc InpucCd llbackProc proc; 
XcPolncer clienc^dacd ; 

Arguments 

app_concexz Specifies the application context that identifies the application. 

source Specifies the source file descriptor (on a POSDC-based system) or other 

operaung-systern-dependent device specification. 

condition Specifies a mask that indicates a read, write, or exception condition or some 
operating-system-dependent condition. 

proc Specifies the procedure that is to be caiied when condition is true. See 

XtInputCallbackProc(2). 

cllenc_dac* Specifies for argument source to be passed to proc when I/O is available. 
Description 

While most applications are driven only by X events, some applications need to incorporate 
other sources of input. XtAppAddlnput allows an application to integrate notification of 
pending file data into the event mechanism. The application uses XtAppAddlnput to regis- 
ter a file with the Incrinsics read routine. When I/O is pending on the file source, the regis-, 
tered callback procedure proc is invoked, source is usually file input but can also be file 
output (Note that "file" means any sink or source of data.) 

XtAppAddlnput also specifies the condition under which source can generate events.-- 
The legal values for condx eion are operating-system-dependcnL On a POSDC-based system, 
the possible values are XtlnputReadMask, XtlnputWriteMask, or Xt Input Except* 
Mask. The masks cannot be ORed together. These limit the invocation of proc to either a 
pending read, write, or exception condition on the source file. See the POSOC system select 
rail for discussion of these conditions. 

Callback procedures that are used when there are file events are of type Xt Input Callback - 
Proc. 

Note that when reading from a socket, you should be careful not to close the end of -the socket 
that is waiting before exiting the XtAppMainLoop. If you do this, you will get an infinite 
loop, in which the proc is called repeatedly, while the Incrinsics wait for an EOF to be read. 

See Chapter 8, More Input Techniques, in Volume Four, X Toolkit Intrinsic* Programming 
Manual, for a complete example using this function. 



86 X Tootut Intrinsic* Reference Manual 
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xt - Event Handling (continued) XtAppAddlnput 
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See Also 

Xtlnp ulCaltbackProc (2 ). 
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j XtRemovelnput 

^Xl - Event Handling ^ 

XtRemovetnput — unregisier a file procedure, a pipe procedure, or a socket procedure. 
Synopsis 

void XtRerrove Cnpuc ( id) 
Xclnpucrd id: 

arguments 

ld Specifies the ID returned from the corresponding xtAppAddlnput call. 

Description 

XtRemovelnput causes the Incnnsics to stop watching for events from an alternate input 
source registered with xtAppAddlnput. Alternate input events are usually operating system 
reads, but they can be any I/O operation supported by the operating system. 
For more general discussion of alternate input events, see Chapter 8. More Inpui Techniques. 
in Volume Four. X Toolkit Intrinsic* Programming Hamuli. 

S6* AlSO 

Xu\ddfnpui{\), XtAppAddInpui{\). 
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XtAppAddTimeOut v v# e 

^ *t- Evant Handling — 

XLAppAddTimeOut — invoke a procedure after a specified timeout. 
Synopsis 

XtTncervalld X: AppAddTi/neOut ( dpp_concexc, interval, proc, clienc_daca) 
XtAppContext app_concexc; 
u ns igned long incecva I; 
XcTimecCalibackProc proc; 
XcPointer clienc^daca; 

is Arguments 

app^concexc Specifies the application context for which the timer is to be seL 

interval Specifies the time interval in milliseconds. 

pcoc Specifies ihe procedure that is to be called when the time expires. See Xt- 

20 TimerCallbackProc(2). 

cllenc_daca Specifies the argument to be passed to the specified procedure when it is 
called. 



Description 

XtAppAddTimeOut allows a program to have a function called after a specified timeout 
XtAppAddTimeOut creates the timeout and returns an identifier for it The length of the 
timeout value is interval milliseconds. 

The Intrinsics invoice the specified callback when interval elapses, and the timeout is 
removed from the event queue. 

The return value xtlntervaliD uniquely identifies the pending timer pseudo-event. The 
pending event can be deleted from the queue before the interval expires by calling Xt- 
RemoveTimeOut. 

The callback procedure pointer that is invoked when timeouts expire is of type Xt Timer - 
CallbackProc. 

xtAppNextEvent and XtAppPeekEvent dispatch timer queue entries. 
See Also 

40 XtAppN€XXEvcru{\) % XtAppP€tkEvcf%t{\) % XtDLspoxchEvcrull), XtRem0*€TimcOux(\) 9 

XaimerCaUbackProcQ.). 
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XtRemoveTimeOut N xt _ £vent Handltng _ 

Name 

XtRemovcTimeOul — unregister a timeout procedure. 
Synopsis 

v/oid XtRemoveTimeOLC ( id) 
X- Inte rva lid id; 

Arguments 

id Specifies the ID for the timeout registration to be destroyed. 

Description 

xtRemoverimeOuc removes the timeout specified by id. id is the value returned by cither 
XtAppAddTimeOuc or XtAddTimeOut. 

Note that timeouts are automatically removed once they expire and the callback has been 
called. 

For an example and discussion of timeouts, sec Chapter 8. More Input Techniques, in Volume 
Four, X Toolkit Intrinsic* Programming Manual. 

See Also 

XtAdJTimeOutO), XtAppAdt£TimcOut{\). 
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Claims 

1. A computer system comprising: 

A. at least one applications program for performing predetermin d processing operations, the applications 
program issuing WinSock socket calls; 

B. a Unix operating system API for providing, in response to Unix socket calls, Unix socket services in con- 
nection with at least one socket connection to another computer system over a network; and 

C. a WinSock socket driver for receiving WinSock socket calls from said applications program and emulating 
said WinSock socket calls in connection with Unix socket calls to said Unix operating system API. 

2. A computer system as defined in claim 1 in which said Unix operating system API provides Unix socket services 
in a blockable pre-emptive multi-tasking manner. 

3. A computer system as defined in claim 1 in which said WinSock socket driver emulates at least one WinSock 
socket call in a non-blockable non-pre-emptive multi-tasking manner. 

4. A computer system as defined in claim 3 in which said WinSock socket driver emulates said at least one WinSock 
socket call in connection with a blockable Unix socket call, the blockable Unix socket call having a duration pa- 
rameter specifying a duration over which a specified operation to be performed, the blockable Unix socket call 
blocking other operations for the duration, the WinSock socket driver including: 

A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 
duration specified by the duration parameter; 

B. a blockable call issuer for issuing the blockable Unix socket call with a duration parameter specifying an 
instantaneous duration thereby enabling the specified operation to be performed instantaneously; and 

C. a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
issue the blockable call until the timer generates the timing indication, the non-blockabie control element being 
non-pre-emptively interruptible during each iteration while the blockable call is not being executed thereby to 
facilitate emulation of the WinSock socket call in a non-blockable manner. 

5. A computer system as defined in claim 4, the WinSock socket driver operating in connection with a pre-emptive 
multi-tasking operating system program which provides a timer call, the timer enabling generation of the timing 
indication by using the timer call with a timer call duration corresponding to the duration specified by the duration 
parameter 

6. A computer system as defined in claim 5 in which the pre-emptive multi-tasking operating system program is the 
Unix operating system program with XWindows extensions. 

7. A computer system as defined in claim 6 in which the timer call comprises the XWindows XtAppAddTimeOutQ call. 

8. A computer system as defined in claim 4, in which the computer system establishes socket network connections 
with at least one other computer over a network, the applications program using the non-blockable call to obtain 
information as lo the status ofa said network socket connection. 

9. A computer system as defined in claim 8 in which blockable call provides information as to a said network socket 
connection. 

10. A computer systom as defined in claim 4 in which the WinSock socket call is a WinSock Synchronous Select call, 
and the blockable Unix socket call is a Unix Synchronous Select call. 

11. A computer system as defined in claim 3 in which said WinSock socket driver mulates said at least one WinSock 
socket call in connection with a non-blockable Unix/XWindows extension call for determining the occurrence ofa 
pred termined event, as determined by the WinSock socket call, in said computer system, th WinSock socket 
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driver including: 

A. a call issuer for issuing the non-blockable Unix/XWindows extension call and providing a call acknowledg- 
ment to the applications program: and 

B. a response receiver for later receiving a response from the Unix/XWindows extension call and providing 
the response to the applications program 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

12. A computer system as defined in claim 11 in which said non-blockable Unix/XWindows extension call comprises 
an XtAppAddlnput() call. 

13. A method of operating a computer system, comprising the steps of: 

A. enabling at least one applications program to performs predetermined processing operations, the applica- 
tions program issuing WinSock socket calls; 

B. emulating the WinSock socket calls to generate Unix socket calls; and 

C. enabling a Unix operating system API to provide, in response to Unix socket calls, Unix socket services in 
connection with at least one socket connection to another computer system over a network. 

14. A method as defined in claim 1 3 in which said Unix socket calls operate in a blockable pre-emptive multi-tasking 
25 manner. 

15. A method as defined in claim 13 in which at least one said WinSock socket call is emulated in a non-blockable 
non-pre-emptive multi-tasking manner. 

-30 16. A method as defined in claim 15 in which said at least one WinSock socket call is emulated in connection with a 
blockable Unix socket call, the blockable Unix socket call having a duration parameter specifying a duration over 
which a specified operation to be performed, the blockable Unix socket call blocking other operations for the du- 
ration, the WinSock socket call being emulated in accordance with the steps of: 

3S A. enabling generation ofa timing indication at the end of a timing interval corresponding to the duration spec- 

ified by the duration parameter; 

B. issuing the blockable Unix socket call with a duration parameter specifying an instantaneous duration th re- 
by enabling the specified operation to be performed instantaneously; and 

40 

C. in a series of iterations, enabling the blockable call issuer to issue the blockable call until the timer generates 
the timing indication, the non-blockable control element being non -pre-emptively interruptible during each 
iteration while the blockable call is not being executed thereby to facilitate emulation of the WinSock socket 
call in a non-blockable manner. 

45 

17. A method as defined in claim 16, in which the emulation step is performed in connection with a pre-emptive multi- 
tasking operating system program which provides a timer call, the generation of the timing indication being enabled 
by using the timer call with a timer call duration corresponding to the duration specified by the duration parameter. 

50 18. A method as defined in claim 17 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

19. A method as defined in claim 18 in which the timer call comprises the XWindows XtAppAddTimoOut() call. 

55 20. A method as defined in claim 16, in which the computer system establishes socket network connections with at 
least one other computer over a network, the non-blockable cat! being used to obtain information as to the status 
of a said network socket connection. 
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21 . Am thod as defined in claim 20 in which blockable call provides information as to a said network socket connection. 

22. A method as defined in claim 16 in which the WinSock sock t call is a WinSock Synchronous Select call, and the 
blockable Unix socket call is a Unix Synchronous Select call. 

5 

23. A method as defined in claim 15 in which said at least one WinSock socket call is emulated in connection with a 
non-blockable Unix/XWindows extension call for determining the occurrence of a predetermined event, as deter- 
mined by the WinSock socket call, in said computer system, the WinSock socket driver including: 

10 A. issuing the non-blockable Unix/XWindows extension call and providing a call acknowledgment to the ap- 

plications program; and 

B. later receiving a response from the Unix/XWindows extension call and providing the response to the appli- 
cations program; 

15 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner 

24. A method as defined in claim 23 in which said non-blockable Unix/XWindows extension call comprises an XtAp- 
pAddlnput() call. 

20 

25. A WinSock socket driver for use in connection with a Unix operating system API, the WinSock socket driver re- 
ceiving WinSock socket calls from an applications program and emulating them using calls to the Unix operating 
system API, the WinSock socket driver including: 

25 A. a WinSock call verification element for, in response to receipt of a WinSock call from said applications 

program, verifying the emulatability of the received WinSock call, 

B. an emulation element for issuing predetermined Unix operating system API calls as determined by the 
received WinSock call, and receiving responses generated in response to said Unix operating system API calls; 

30 

C. a response generation element for generating a response to said WinSock socket driver call for provision 
to said applications program. 

26. A WinSock socket driver as defined in claim 25 in which said WinSock call verification element, in verifying the 
3S emulatabililty of the received WinSock call, verifies any parameters provided in the call. 

27. A WinSock socket driver as defined in claim 25 in which said WinSock socket driver emulates said at least one 
WinSock socket call in connection with a blockable Unix socket call, the blockable Unix socket call having a duration 
parameter specifying a duration over which a specified operation to be performed, the blockable Unix socket call 

40 blocking other operations for the duration, the WinSock socket driver including: 

A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 
duration specified by the duration parameter; 

45 B. a blockable call issuer for issuing the blockable Unix socket call with a duration parameter specifying an 

instantaneous duration thereby enabling the specified operation to be performed instantaneously; and 

C. a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
issue the blockable call until the timer generates the timing indication, the non-blockable control element being 
50 non-pre-emptively interruptible during each iteration while the blockable call is not being executed thereby to 

facilitate emulation of the WinSock socket call in a non-blockable manner. 

28. A WinSock socket driver as defined in claim 27, the WinSock socket driver operating in connection with a pre- 
emptive multi-tasking operating system program which provides a timer call, the timer enabling generation of the 

55 timing indication by using the timer call with a timer call duration corresponding to th duration specified by the 

duration parameter. 

29. A WinSock sock t driver as defin d in claim 28 in which the pre-emptive multi-tasking op rating system program 
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is the Unix operating system program with XWindows extensions. 

30. A WinSock socket driver as defined in claim 29 in which the timer call compris s the XWindows Xt AppAddTimeOut 
() call. 

5 

31. A WinSock socket driver as defined in claim 27, in which the computer system establishes socket network con- 
nections with at least one other computer over a network, the applications program using the non-blockable call 
to obtain information as to the status of a said network socket connection. 

10 32. A WinSock socket driver as defined in claim 31 in which blockable call provides information as to a said network 
socket connection. 

33. A WinSock socket driver as defined in claim 27 in which the WinSock socket call is a WinSock Synchronous Select 
call, and the blockable Unix socket call is a Unix Synchronous Select call. 

15 

34. A WinSock socket driver as defined in claim 26 in which said WinSock socket driver emulates said at least one 
WinSock socket call in connection with a non-blockable Unix/XWindows extension call for determining the occur- 
rence of a predetermined event, as determined by the WinSock socket call, in said computer system, the WinSock 
socket driver including: 

20 

A. a call issuer for issuing the non-blockable Unix/XWindows extension call and providing a call acknowledg- 
ment to the applications program; and 

B. a response receiver for later receiving a response from the Unix/XWindows extension call and providing 
25 the response to the applications program 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

35. A WinSock socket driver as defined in claim 34in which said non-blockable Unix/XWindows extension call com- 
30 prises an XtAppAddlnput() call 

36. A method for emulating WinSock socket calls from an applications program in connection with a Unix operating 
system API, the method including the steps of: 

35 A, verifying, in response to receipt of a WinSock call from said applications program, the emulatability of the 

received WinSock call, *" 

B. issuing predetermined Unix operating system API calls as determined by the received WinSock call, and 
receiving responses generated in response to said Unix operating system API calls; 

40 

C. generating a response to said WinSock socket driver call for provision to said applications program. 

37. A method as defined in claim 36 in which, during the verification step, any parameters provided in the call are 
verified. 

45 

38. A method as defined in claim 36 in which at least one said WinSock socket call is emulated in a non-blockable 
non-pre-emptive multi-tasking manner. 

39. A method as defined in claim 33 in which said at least one WinSock socket call is emulated in connection with a 
50 blockable Unix socket call, the blockable Unix socket call having a duration parameter specifying a duration over 

which a specified operation to be periormed, the blockable Unix socket call blocking other operations for the du- 
ration, the WinSock socket call being emulated in accordance with the steps of: 

A. enabling generation ofa timing indication at the end of a timing interval corresponding to the duration spec- 
55 jfied by th duration paramet r; 

B issuing the blockable Unix socket call with a duration parameter specifying an instantaneous duration there- 
by enabling the specified operation to be periormed instantaneously; and 
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C. in a series of iterations, enabling the blockable call issuer to issue the blockable call until the timer generates 
the timing indication, the non-blockable control element being non-pre-emptively tnterruptible during each 
iteration whil the blockable call is not being executed thereby to facilitate emulation of the WinSock socket 
call in a non-blockable manner. 

5 

40. A method as defined in claim 39 in which the emulation step is performed in connection with a pre-emptive multi- 
tasking operating system program which provides a timer call, the generation of the timing indication being enabled 
by using the timer call with a timer call duration corresponding to the duration specified by the duration parameter. 

10 41. A method as defined in claim 40 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

42. A method as defined in claim 41 in which the timer call comprises the XWindows XtAppAdd71meOut() call. 

is 43. A method as defined in claim 39, in which the computer system establishes socket network connections with at 
least one other computer over a network, the non-blockable call being used to obtain information as to the status 
ofa said network socket connection. 

44. A method as defined in claim 43 in which blockable call provides information as to a said network socket connection. 

20 

45. A method as defined in claim 39 in which the WinSock socket call is a WinSock Synchronous Select call, and th 
blockable Unix socket call is a Unix Synchronous Select call. 

46. A method as defined in claim 38 in which said at least one WinSock socket call is emulated in connection with a 
2S non-blockable Unix/XWindows extension call for determining the occurrence of a predetermined event, as deter- 
mined by the WinSock socket call, in said computer system, the WinSock socket driver including: 

A. issuing the non-blockable Unix/XWindows extension call and providing a call acknowledgment to the ap- 
plications program; and 

30 B. later receiving a response from the Unix/XWindows extension call and providing the response to the appli- 

cations program; 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

35 47. A method as defined in claim 46 in which said non-blockable Unix/XWindows extension call comprises an XtAp- 
pAddlnputO call. 

48. For use in connection with a computer, a non -pre-emptive multi-tasking emulator for emulating a blockable call 
issued by an applications program, the blockable call having a duration parameter specifying a duration over which 

40 a specified operation to be performed, the blockable call blocking other operations for the duration, the emulator 

emulating the blockable call in a non-blocking manner, the emulator comprising; 

A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 
duration specified by the duration parameter; 

45 

B. a blockable call issuer for issuing the blockable call with a duration parameter specifying an instantaneous 
duration thereby enabling the specified operation to be performed instantaneously; and 

C. a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
50 issue the blockable call until the timer generates the timing indication, the non-blockable control element being 

non-pre-emptively interruptible during each iteration while the blockable call is not being executed. 

49. An emulator as defined claim 48 in which the blockable call operates in a polling mode in which it performs the 
operation instantaneously and a non-polling mode in which it performs the operation over a selected period of 

ss time, the mode being indicated by th duration parameter, the blockabl call issuer issuing th blockable call using 

the duration parameter which indicates the polling mode. 

50. An emulator as defined in claim 48 in which th blockable call is executed by a pre-emptive multi-tasking operating 
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system program. 

51. An emulator as defined in claim 50 in which the pre-emptive multi-tasking operating system program is the Unix 
operating syst m program. 

5 

52. An emulator as defined in claim 48, the mulator operating in connection with a pre-emptive multi-tasking operating 
system program which provides a timer call, the timer enabling generation of the timing indication by using the 
timer call with a timer call duration corresponding to the duration specified by the duration parameter 

io 53. An emulator as defined in claim 52 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

54. An emulator as defined in claim 48 in which the computer establishes socket network connections with at least 
one other computer over a network, the applications program using the non-blockable call to obtain information 

'5 as to the status of a said network socket connection. 

55. An emulator as defined in claim 54 in which blockable call provides information as to a said network socket con- 
nection. 

20 56. A method of controlling a computer to emulate, in a non-pre-emptive multi-tasking manner, a blockable call, the 
blockable call having a duration parameter specifying a duration over which a specified operation to be performed, 
the blockable call blocking other operations for the duration, the blockable call being emulated in a non-blocking 
manner, the method comprising the steps of: 

25 A. enabling generation of a timing indication at the end of a timing interval corresponding to the duration 

specified by the duration parameter; 

B. issuing the blockable call with a duration parameter specifying an instantaneous duration thereby enabling 
the specified operation to be performed instantaneously; and 

30 

C. in a series of iterations, enabling the issuance of the blockable call until the timing indication is generated, 
the operations being non-pre-emptively interruptible during each iteration while the blockable call is not being 
executed. 

35 57. A method as defined claim 56 in which the blockable call operates in a polling mode in which it performs the 
operation instantaneously and a non-polling mode in which it performs the operation over a selected period of 
time, the mode being indicated by the duration parameter, the blockable call being issued using the duration pa- 
rameter which indicates the polling mode. 

40 58. A method as defined in claim 56 in which the blockable call is executed by a pre-emptive multi-tasking operating 
system program. 

59. A method as defined in claim 58 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program. 

•45 

60. A method as defined in claim 56, the method being performed in connection with a pre-emptive multi-tasking 
operating system program which provides a timer call, the timing indication by use of the timer call with a timer 
call duration corresponding to the duration specified by the duration parameter. 

so 61. A method as defined in claim 60 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

62. A method as defined in claim 56, in which the computer establishes sockot network connections with at least one 
other computer over a network, the applications program using the non-blockable call to obtain information as to 

55 the status of a said network sock t connection. 

63. A method as defined in claim 62 in which blockable call provides information as to a said network socket connection 
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100. RECEIVE A WINSOCK SYNCHRONOUS SELECT 
CALL FROM AN APPLICATIONS PROGRAM 21 AND 
OBTAIN THE CONTEXT OR TASK IDENTIFIER THEREOF 



101. VERIFY THAT SOCKET STRUCTURE HAS BEEN 
INITIALIZED FOR THE TASK IDENTIFIED BY THE TASK 
IDENTIFIER BY WAY OF A SOCKET START CALL 



YES 
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NO 

4 



102. RETURN AN ERROR VALUE 



J 



103. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
WITH THE APPLICATIONS PROGRAM 21 WHICH HAS 
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NO 
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104. RETURN AN ERROR VALUE 
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^05. ACCESS SOCKET IDENTIFIER TABLE(S) WHICH 
ARE IDENTIFIED BY THE -RD-SOCK-PTR" READ 
SOCKET POINTER, "WRT-SOCK-PTR" WRITE SOCKET 
POINTER AND "EXC-SOCK-PTR" EXCEPTION SOCKET 
POINTER PARAMETERS AND OBTAIN UNIX FILE 
DESCRIPTOR INFORMATION FOR SOCKET 
.IDENTIFIERS LISTED THEREIN 



NO 



106. DETERMINE WHETHER ERROR ENCOUNTERED IN 
CONNECTION WITH SOCKET IDENTIFIERS OR 
GENERATION OF THE UNIX FILE DESCRIPTOR 
INFORMATION 

v 1 " 

YES 



107. RETURN AN ERROR VALUE 



J 



YES" 



108. DETERMINE WHETHER THE TM-OUT TIMEOUT 
DURATION PARAMETER SPECIFIED A NULL VALUE. 
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109. DETERMINE WHETHER THE TIMEOUT DURATION 
PARAMETER SPECIFIED A ZERO VALUE 




NO 
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110 ISSUE AM XtAppAddTlmoOutO XWINDOWS CALL 
TO THE UNIX OPERATING SYSTEM PROGRAM AND 
SET A TIMER TASK 



3 



111. ISSUE APPROPRIATE UNIX SOCKETS' UNIX 
SYNCHRONOUS SELECT CALL WITH TIMEOUT 
DURATION OF ZERO 



r 112. AFTER RETURNING FROM THE UNIX 
SYNCHRONOUS SELECT CALL, TEST THE "TM-OUT' 
TIMEOUT DURATION PARAMETER PROVIDED IN THE 
WJNSOCK SYNCHRONOUS SELECT CALL TO 
DETERMINE WHETHER IT WAS NON-ZERO 



NO 
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YES 



113. DETERMINE WHETHER THE VALUE PROVIDED IN 
RESPONSE TO THE UNIX SYNCHRONOUS SELECT 
CALL PROVIDED A NON-ZERO RESPONSE 
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NO 

i. 



YES 



114. CALL BLOCKING HOOK FUNCTION AND 
DETERMINE WHETHER (i) THE APPLICATIONS 
PROGRAM 21 HAS TERMINATED THE WINSOCK 
SYNCHRONOUS SELECT OPERATION OR (ii) THE 
TIMER TASK FLAG HAS BEEN CLEARED BY THE 
TIMING OUT OF THE XtAppAddTinieOut() CALL- 
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115. TERMINATE OPERATIONS AND RETURN TO THE 
CALLJNG APPLICATIONS PROGRAM 



116. ISSUE AN XtRerooveTmwOut XWINDOWS CALL TO 
CANCEL THE XtAppAddTinwOut CALL 



3 



117. CLEAR THE TIMER TASK FLAG 



i18. IDENTIFY THE PARTICULAR SOCKET(S) 
DETERMINED TO BE READABLE, WRITABLE OR FOR 
WHICH AN EXCEPTION WAS DETECTED AND 
CONVERT THE SOCKET IDENTIFIERS FROM THE UNIX 
FILE DESCRIPTOR IDENTIFIERS TO SOCKET 
vjDENTtFIERS 



119. RETURN TO CALLING APPLICATIONS PROGRAM 
21 
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130. RECEIVE AN ASYNCHRONOUS SELECT CALL 
FROM AN APPLICATIONS PROGRAM 21 AND OBTAIN 
THE CONTEXT OR TASK IDENTIFIER THEREOF 
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131. VERJFY THAT THE SOCKET STRUCTURE HAS 
BEEN INITIALIZED FOR THE TASK IDENTIFIED BY 
THE TASK IDENTIFIER BY WAY OF A SOCKET START 
CALL 

NO 

. * 



132. RETURN AN ERROR VALUE 
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YES 



133. DETERMINE WHETHER "SOCK-JD" SOCKET 
IDENTIFIER PARAMETER IS A VALID SOCKET 
IDENTIFIER AND IF THE APPLICATIONS PROGRAM 21 
HAS PERMISSION TO ACCESS THE SOCKET 
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NO 
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134. RETURN AN ERROR VALUE 
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NO 



135. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
WITH THE APPLICATIONS PROGRAM 21 WHICH HAS 
NOT BEEN COMPLETED 
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YES 



136. RETURN AN ERROR VALUE 
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137. CLEAR A -BLOCKING" FLAG 



T 



138. DETERMINE WHETHER THE CALL IS TO 
RE-ENABLE NOTIFICATION FOR A NETWORK EVENT 



YES 

JL 



139. ADD THE TYPE OF NETWORK EVENT FOR 
WHICH THE APPLICATIONS PROGRAM 21 IS TO BE 
NOTIFIED TO A UST OF NETWORK EVENTS TO BE 
MONITORED 



f\40. SUBSTITUTE THE NETWORK EVENT IDENTIFIED^ 
BY THE "EY-ID" EVENT IDENTIFIER PARAMETER FOR 
THE MONITORED NETWORK EVENT UST AND ISSUE 
Unix/XWindow* XtRamovelnputO CALL(S) TO THE 
Unix/XWindows OPERATING SYSTEM PROGRAM TO 

VENABLE IT TO STOP MONITORlNJSgF^IETyvORK^ 
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"141. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A SOCKET-CLOSE EVENT OR AN 
OUT-OF-BAND DATA RECEIVED EVENT 



YES 



142. GENERATE AN XtAppAddlnput() CALL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XtinputExceptMask -EXCEPTION" MASK 
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143. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A SOCKET-ACCEPT EVENT OR A READ 
READINESS NOTIFICATION 



YES 

_4_ 



144. GENERATE AN XtAppAddlnputf) CALL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XUnputReadMask -READ** MASK 



r 145. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A COMPLETED^SOCKET-CONNECTION 
NOTIFICATION OR A WRJTE-READINESS 
NOTIFICATION 



YES 



146. GENERATE AN XtAppAddlnput{) CALL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XtlnputWnteMask "WRITE" MASK 



147. PROVIDE A RETURN ACKNOWLEDGMENT 
VALUE TO THE APPLICATIONS PROGRAM 21 WHICH 
ISSUED THE ASYNCHRONOUS SELECT CALL 
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150. RECEIVE RESPONSE TO XtAppAddlnput() CALL 



151. TEST A RE-ENTRANT CONTROL FLAG TO 
DETERMINE WHETHER IT IS CURRENTLY 
PROCESSING A RESPONSE 



NO 

1 



152 CONDITION THE RE-ENTRANT CONTROL FLAG 
TO INDICATE THAT IT IS CURRENTLY PROCESSING 

RESPONSE 

v — 



153. DETERMINE THE TYPE OF RESPONSE 



I 



154. GENERATE A MESSAGE IDENTIFYING THE 
RESPONSE 



I 



155. POST MESSAGE IN A RESPONSE QUEUE 
ASSOCIATED WITH THE CALLING APPLICATIONS 
PROGRAM 21 



I 



156. CONDITION THE RE-ENTRANT CONTROL FLAG 
TO INDICATE THAT IT IS NOT CURRENTLY 
PROCESSING A RESPONSE 

v 



FIG. 4C 



8NSDOCID <EP 0770958A1 I > 



165 



EP 0 770 958 A1 



European Patent 
Office 



EUROPEAN SEARCH REPORT 



Application fS umber 

EP 96 30 7735 



DOCUMENTS CONSIDERED TO BE RELEVANT 



Category 



Citation of document with indication, where appropriate, 
of retevaat parages 



Relevant 
to claim 



CLASSIFICATION OF THE 
APPLICATION (IM.CL6) 



D,A 



D,A 



MARTIN HALL ET AL.: "Windows Sockets: An 
Open Interface for Network Programing 
under Microsoft Windows; Version 1.1" 
20 January 1993 , USA XP002025353 

* page 12, last paragraph - page 13. line 
41 * 

* page 15, last paragraph - page 16, 
paragraph 1 * 

* page 96, line 1 - page 97, last line * 

* page 101, line 1 - page 103, last line * 

* page 109 * 

O'REILLY & ASSOCIATES, INC.: "X Toolkit 
Intrinsics Reference Manual, Second 
Edition for Xll Release 4" 
1990 , USA XPG02025354 

* page 86, line 1 - page 88, last line * 

* page 301 * 

* page 304 * 

DATA COMMUNICATIONS, 
vol. 22, no. 14, 1 October 1993, 
page 117/118, 120, 122 XP000398909 
SPARLING C: "PLUGGING INTO TCP/IP WITH 
WINDOWS SOCKETS" 

* page 120, right-hand column, last 
paragraph - page 122, middle column, 
paragraph 1 * 



1,13,25, 
36,48,56 



G06F9/455 
G06F13/10 



Tae present scare* report has been drawn up for all claims 



1,13,25, 
36,48,56 



1,13,25, 
36,48,56 



TECHNICAL FIELDS 
SEARCHED (IblCJ.61 



G06F 



THE HAGUE 



D«e U cnnplcUM of tae mmtk 

14 February 1997 



Fonderson, A 



CATEGORY OF CITED DOCUMENTS 

X : particularly relevant If taken alone 

V : particularly relevant if combined with another 

document of the same category 
A : technological background 
O : •oa-writfea d it cloture 
P r intermediate doeameat 



1 : theory or principle underlying the invention 
E : earlier patent document, but paWitbod on, ce 

after the filing date 
D : document cited in the application 
L : document cited for other reasons 



: m«mb«r of the tuu patent family, 
document 



RNSDOCID <FP 0770958A1 I > 



166 



EP 0 77C 95ft A1 




BNSDOCID <EP 0770958A1TI > 



1« 



EP 0 77C95B A1 



WINDOWS 
APPLICATIONS 
PROGRAM 21 




WINDOWS 
APPLICATIONS 
PROGRAM 21 




WINDOWS 
APPLICATIONS 
PROGRAM 21 


WINDOWS 






i 

\ 


\ 
t 








EMULATOR 
17 


WINDOWS ' 

api . : 

18 


W1NSOCK 
SOCKET 
DRIVER 1 9 





7; 



OPERATING SYSTEM 
API 20 



UNIX 

NETWORK 
SOCKET 
DRIVER 23 
? — 



TCP/IP SftCK 
MODULE 24 



NETWORK 
PORT 14 



> 22 



■31 



FIG 2 



RNSOOTlO <FP 0770958A1T) > 



1&7 



EP 0 770 958 A1 



100. RECEIVE A W1NSOCK SYNCHRONOUS SELECT 
CALL FROM AN APPLICATIONS PROGRAM 2\ AND 
OBTAIN THE CONTEXT OR TASK IDENT1FJER THEREOF 



J 



101. VERIFY THAT SOCKET STRUCTURE HAS BEEN 
INITIALIZED FOR THE TASK IDENTIFIED SY THE TASK 
IDENTIFIER BY WAY OF A SOCKET START CALL 
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NO 
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102. RETURN AN ERROR VALUE I 



103. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
YWTH THE APPLICATIONS PROGRAM 21 WHICH HAS 
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105. ACCESS SOCKET IDENTIFIER TABLE(S) WHICH 
ARE IDENTIFIED BY THE "KIVSOCK-PTR" READ 
SOCKET POINTER, -WftT-SOCK-PTR" WRITE SOCKET 
POINTER AMD "EXC-SOCK-PTR" EXCEPTION SOCKET 
POINTER PARAMETERS AND OBTAIN UNIX FILE 
DESCRIPTOR INFORMATION FOR SOCKET 
IDENTIFIERS LISTED THEREIN 
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106. DETERMINE WHETHER ERROR ENCOUNTERED IN 
CONNECTION WITH SOCKET IDENTIFIERS OR 
GENERATION OF THE UNIX FILE DESCRIPTOR 
INFORMATION 
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107. RETURN AN ERROR VALUE 
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DURATION PARAMETER SPECIFIED A NULL VALUE, 




109. DETERMINE WHETHER THE TfMEOUT DURATION 
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TO THE UNIX OPERATING SYSTEM PROGRAM AND 
SET A TIMER TASK 
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115. TERMINATE OPERATIONS AND RETURN TO THE 
CALLING APPLICATIONS PROGRAM 
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135. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
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NOT SEEN COMPLETED 
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137. CLEAR A "BLOCKING" FLAG 
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150. RECEIVE RESPONSE TO KtAppAddJnput() CALL 
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